Internet Security and Acceleration Server 2000

Internet Security and Acceleration Server 2000 Start Page

Microsoft Internet Security and Acceleration (ISA) Server 2000

Version 3.0

Purpose

Microsoft® Internet Security and Acceleration (ISA) Server 2000 is an extensible platform that integrates firewall and cache features, and routes requests and responses between the Internet and client computers. ISA Server provides filtering to block access to specific sites, and uses network address translation (NAT) and other methods to enable secure access between an intranet and the Internet. This documentation includes information and libraries for developing firewall extensions, administration tools, security applications, and other components that integrate with and build on the ISA platform.

Where Applicable

ISA Server includes firewall services, advanced caching capabilities, packet filtering, and alerting. This documentation includes information relevant to developers wanting to extend these features.

Audience

The information in this documentation for ISA Server is relevant to programmers, system administrators, and tool vendors. To use this documentation programming experience in the following areas is desirable:

•Visual C++® or Visual Basic® applications

•Visual Basic Scripting Edition (VBScript) or JScript®

Run-Time Requirements

To run ISA Server requires Microsoft Windows® 2000 Server.

Overview

General information about ISA Server.

Implementation

How to use ISA Server.

Reference

Documentation of ISA Server administration COM objects, interfaces, structures, and enumerated types.

Feedback

Make error reports and feature requests directly to Microsoft.

Built on Monday, December 04, 2000


Legal Information

Microsoft Internet Security and Acceleration (ISA) Server 2000

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

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.

Unpublished work. © 2000 Microsoft Corporation. All rights reserved.

Microsoft, Windows, Windows NT, Active Directory, ActiveX, DirectX, JScript, MSDN, NetShow, Visual Basic, Visual C++, Visual Studio, and Win32 are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Macintosh is a trademark of Apple Computer, Inc., used under license.

Intrusion detection functionality based on technology from Internet Security Systems, Inc., Atlanta, GA, USA, www.iss.net. Portions Copyright © 2000 Internet Security Systems, Inc.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


About Internet Security and Acceleration Server

Microsoft® Internet Security and Acceleration (ISA) Server 2000 integrates firewall and cache features to secure networks and improve their performance. ISA Server is an extensible platform that provides security, hardware redundancy and load balancing, efficient use of network resources by means of sophisticated caching mechanisms, and administration tools. ISA Server runs on computers that use the Microsoft Windows® 2000 Server operating system, and relies on the features and functionality of the operating system.

ISA Server consists of several technologies:

  • Firewall service.
  • Web proxy service.
  • Secure network address translation (SecureNAT).
  • Advanced caching capabilities, including RAM caching and use of the Cache Array Routing Protocol (CARP).
  • Bandwidth control.
  • Static and dynamic Internet Protocol (IP) packet filtering.
  • Alerting.

For more information, see the ISA product documentation.

Two editions of ISA Server are available: ISA Server Standard Edition and ISA Server Enterprise Edition. Initially, an organization may decide to purchase ISA Server Standard Edition. As the organization grows, and the need to communicate with the Internet increases, consider upgrading from the ISA Server Standard Edition to the Enterprise Edition. The differences between the editions are documented in Enterprise Edition and Standard Edition.

This section contains the following topics:

  • Installing the ISA Server Software Development Kit
  • About this Documentation
  • ISA Server Overview
  • About ISA Server Administration
  • About the ISA Server Firewall
  • About the ISA Server Cache
  • About ISA Server Rules
  • About Authentication in ISA Server
  • About ISA Server Services
  • About ISA Server Clients
  • About ISA Server Setup


Installing the ISA Server Software Development Kit

The ISA Server Software Development Kit (SDK) provides an installation script that does the following:

  • Copies the SDK files to the directory of your choice.
  • Copies binaries of the ISA COM objects and registers them.

The script is called install.cmd, and is located in the SDK directory on the ISA Server CD.

The command to run the script is:

install <source_directory> <target_directory>

where <source_directory> is the directory of the SDK files on the ISA Server CD, and <target_directory> is the directory where you want to install the SDK.

Note The installation script is designed to be executed by Cmd.exe. It may not run correctly under other command processors. Therefore, if you're using another command processor, run cmd /c path \install.cmd.


About this Documentation

This section contains important information about the ISA Server SDK documentation, in two topics:

  • Using the Header Buttons
  • Syntax in the SDK Documentation


Using the Header Buttons

This version of the ISA Server SDK documentation includes the following header and button bar at the top of many of the topics.

The buttons appear only if the related feature is provided in the topic. The buttons indicate the following features.

The topic contains a See Also section.

To view the See Also links without scrolling to that section, click the button.

The topic contains a Requirements section.

To view the Requirements section without scrolling to that section, click the button.

The topic contains paragraphs that are specific to the programming language.

To view all language-specific paragraphs, click the button, then select Show All. To view the paragraphs for one language only, click the button, then select the preferred language (such as C/C++ or Visual Basic).


Syntax in the SDK Documentation

The ISA Server SDK documentation provides syntax for the Visual Basic Scripting Edition and C++ languages. Each language uses different conventions.

VBScript Syntax

The following conventions are used for presentation of VBScript syntax in the administration COM object properties.

Read-only (get) properties:

[ lCount = ] FPCWebPublishingRules.Count

Write-only (put) properties:

FPCCredentials.Password [ = sPassword ]

For read-write properties, the write syntax is shown:

FPCServer.Description [ = sDescription ]

C++ Syntax

For the administration COM object properties, the read (get) and write (put) syntaxes are always provided, as appropriate for that property.

For read-write properties, an [in, out] parameter is described under the Parameters heading. Otherwise, [in] parameter information is provided under the Parameters heading, and [out] parameter information is provided under the Return Values heading.

For the Filter interfaces, [in] and [out] parameters are labeled as such.


ISA Server Overview

Internet Security and Acceleration (ISA) Server offers a complete Internet connectivity solution that contains both an enterprise firewall and a complete Web cache solution. These services are complementary — you can use either or both of these functions when you install ISA Server in your network.

ISA Server secures your network, allowing you to implement your business security policy by configuring a broad set of rules that specify which sites, protocols, and content can be passed through the ISA Server computer. ISA Server monitors requests and responses between the Internet and internal client computers, controlling who can access which computers on the corporate network. ISA Server also controls which computers on the Internet can be accessed by internal clients.

This section provides basic information regarding the architecture of ISA Server. This information is useful to developers who require a broad view of ISA Server before developing extensions and filters using the ISA Server Software Development Kit (SDK).

This section includes the following topics:

  • Firewall and Security Overview
  • Cache Overview

The section also includes the diagrams for network and server views.


Firewall and Security Overview

ISA Server can be deployed as a dedicated firewall that acts as the secure gateway to the Internet for internal clients. ISA Server protects all communication between internal computers and the Internet. In a simple firewall scenario, the ISA Server computer has two network interface cards, one connected to the local network and one connected to the Internet.

You can use ISA Server to configure the firewall, configuring policies and creating rules to implement your business guidelines. By setting the security access policies, you prevent unauthorized access and malicious content from entering the network. You can also restrict what traffic is allowed for each user and group, application, destination, content type, and schedule.

ISA Server includes the following firewall and security features:

  • Outgoing access policy. You can use ISA Server to configure site and content rules and protocol rules that control how your internal clients access the Internet. Site and content rules specify which sites and content can be accessed. Protocol rules indicate whether a particular protocol is accessible for inbound and outbound communication. For more information, see Controlling Outgoing Requests.
  • Intrusion detection. Integrated intrusion detection mechanisms can alert you when a specific attack is launched against your network. For example, you can configure the ISA Server to alert you if a port scanning attempt is detected. For more information, see Intrusions and Alerts.
  • Application filters. ISA Server controls application-specific traffic with data-aware filters. ISA Server uses the filters to determine if packets should be accepted, rejected, redirected, or modified. For more information, see Application Filters.
  • Authentication. ISA Server supports the following user authentication methods: Integrated Windows authentication, client certificates, digest, and basic. For more information, see About Authentication in ISA Server.


Cache Overview

ISA Server implements a cache of frequently-requested objects to improve network performance. You can configure the cache to ensure that it contains the data that is most frequently used by the organization or accessed by your Internet clients.

ISA Server can be used to allow communication between your local network and the Internet. Communication may be internal clients accessing servers on the Internet—in this case, ISA Server implements forward caching. Communication may be external clients accessing internal, publishing servers—for this case, ISA Server features reverse caching. Both scenarios can benefit from the ability of ISA Server to cache information, making it more quickly available to users.

ISA Server caching features include:

  • Distributed caching. When you set up an array of ISA Server computers, you benefit from distributed content caching. ISA Server uses the Cache Array Routing Protocol (CARP) to enable multiple ISA Server computers to be arrayed as a single logical cache.
  • Hierarchical caching. ISA Server further extends distributed caching by allowing you to set up a hierarchy of caches, chaining together arrays of ISA Server computers, so that clients can access objects from the cache geographically nearest them.
  • Scheduled caching. Use the scheduled cache content download service to configure when the ISA Server should fetch commonly-requested content from the Internet to its cache.
  • Reverse caching. ISA Server can cache content of publishing Web servers, thereby improving their performance and accessibility. All ISA Server caching features are applicable for the content on published servers.

For more information about the ISA Server cache, see About the ISA Server Cache.

Forward caching

ISA Server can be deployed as a forward caching server that provides internal clients with access to the Internet. ISA Server maintains a centralized cache of frequently requested Internet objects that can be accessed by any web-browser client. Objects served from the disk cache require significantly less processing than objects served from the Internet. This improves client browser performance, decreases user response time, and reduces bandwidth consumption on your Internet connection.

Reverse caching

ISA Server can be deployed in front of an organization's Web server that is hosting a commercial Web business or providing access to business partners. With incoming Web requests, ISA Server can impersonate a Web server to the outside world, fulfilling client requests for Web content from its cache. ISA Server forwards requests to the Web server only when the requests cannot be served from its cache.


Network View

The following figure shows the architecture of ISA Server on the network scale.

ISA Server is typically configured on a computer with two network interfaces. One network interface connects directly to the private network, while the other interface connects to the public Internet. The interfaces can be any type that permits protocol bindings. On a local area network (LAN), for example, Ethernet, token ring network, or Attached Resource Computer Network (ARCnet) is commonly bound to Transmission Control Protocol/Internet Protocol (TCP/IP) or NetBIOS Enhanced User Interface (NetBEUI). An Internet connection might use a modem, Integrated Services Digital Network (ISDN), or network interface that connects to a router that connects to the Internet.

At the center of ISA Server is the administrator's computer. The administrator's computer links the functionality of the ISA Server, the Active Directory™ in Microsoft® Windows® 2000, and the ISA Component Object Model (COM) object. The administrator can also manage clients from a remote location by using either ISA Management or scripting. For information on ISA Management, see the ISA product documentation. For more information on scripting, see ISA Administration Scripting.

Note Enterprise Edition arrays use Active Directory. A stand-alone enterprise server, or a Standard Edition server, would be registry-based. For more information on the two editions, see Enterprise Edition and Standard Edition.

The administrator's tasks include establishing ISA Server rules and policies, and configuring the cache. ISA Server rules determine how ISA Server clients communicate with the Internet and the type of communication that is allowed. These rules also determine how servers on your local network communicate with Internet users. A policy consists of site and content rules, protocol rules, Web publishing rules, and IP packet filters.

A policy can be applied at the array level or the enterprise level. The enterprise consists of all the arrays in the network. Enterprise policies can be applied to all or some of the arrays in the enterprise. In addition, an array policy may apply to one or more arrays. For more information, see the ISA product documentation.

Four items are shown in the network view figure:

  • The remote computer from which an administrator administers ISA Server.
  • The ISA Server array, consisting of at least one computer. The ISA Server array is shown in the Server View figure.
  • Active Directory, located on a separate computer. Active Directory stores information about all the objects on a network, including users and computers, and stores enterprise and domain-array policy and registration information related to ISA and its extensions. Active Directory distributes that information throughout the network. The registry on the ISA computer can perform these functions where Active Directory is not in use.

    For more information, see Active Directory in the Windows 2000 documentation.

  • The clients and servers that use the ISA Server firewall and cache capabilities.

You can programmatically perform or automate ISA administration tasks by accessing the ISA COM objects. For more information, see ISA Administration Scripting.


Server View

ISA Server works at various communication layers to protect the corporate network. At the packet layer, ISA Server implements packet filtering. When packet filtering is enabled, ISA Server can statically control data on the external interface, evaluating inbound traffic before it has the chance to reach any resource. If the data is allowed to pass the packet filtering layer, it is passed to the Firewall and Web proxy services, where ISA Server rules are processed to determine if the request should be serviced.

The following figure shows in detail the architecture of the ISA Server array.

An ISA Server may be included in an array, to allow for load balancing and fault tolerance. This is described further in the ISA product documentation. The following explanation focuses on the architecture of a single ISA server. The server includes these components:

• IP packet filter. As shown, the ISA server as a whole relies on the function of the IP packet filter. For more information, see IP Packet Filtering.

• SecureNAT. A function of ISA Server that performs network address translation (NAT) in place of the Windows 2000 NAT function. For more information, see Secure Network Address Translation.

  • The firewall, consisting of the Web proxy service, Firewall service, and application filters:
    • Web proxy service. Includes Web (ISAPI) filters and the cache.
    • Firewall service. Handles connect requests by Firewall service and SecureNAT clients. HTTP requests are diverted to the Web proxy service by the HTTP redirector filter.
    • Application filters. These include the HTTP redirector filter, which redirects HTTP requests to the Web proxy service, and other protocol filters provided with ISA Server. Third-party filters can be developed for the ISA firewall by using the application filter interfaces.

ISA Server also makes use of the bandwidth control of Quality of Service (QOS) in Windows 2000. QOS is a collection of components that manages bandwidth use for a network. ISA Server applies QOS to connections according to rules established by the ISA administrator.

As shown in the diagram, ISA Server protects three types of clients:

  • ISA Firewall clients are computers that have ISA Firewall client software installed. Requests from ISA Firewall clients are directed to the ISA Firewall service on the ISA Server computer to determine whether access is allowed. Subsequently, the requests can be filtered by application filters and other add-ins. If the ISA Firewall client requests an HTTP object, the HTTP redirector filter redirects the request to the Web proxy service. The Web proxy service may also cache the requested object, or serve the object from the ISA Server cache. For more information on Firewall clients, see Firewall Clients.
  • SecureNAT clients are computers that do not have ISA Firewall client software installed. Requests from SecureNAT clients are directed first to the NAT driver, which substitutes a global IP address that is valid on the Internet for the internal IP address of the SecureNAT client. The client request is then directed to the ISA Firewall service, to determine whether access is allowed. Finally, the request can be filtered by application filters and other add-ins. If the SecureNAT client requests an HTTP object, the HTTP redirector filter redirects the request to the Web proxy service. The Web proxy service may also cache the requested object, or serve the object from the ISA Server cache.
  • Web proxy clients are any browser applications compatible with the standards of Conseil Europeen pour la Recherche Nucleaire (CERN). ISA redirects requests from Web proxy clients to the Web proxy service on the ISA Server computer to determine whether access is allowed. The Web proxy service can also cache the requested object or serve the object from the ISA Server cache.

Note Firewall client and SecureNAT clients are mutually exclusive — that is, a client computer cannot be both a Firewall client and SecureNAT client. However, Firewall client computers and SecureNAT client computers might also be Web proxy clients. If the Web application on the computer is configured explicitly to use the ISA Server, then all Web requests (HTTP, FTP, HTTP-S, and Gopher) are sent directly to the Web proxy service. All other requests are handled first by the Firewall service.


About ISA Server Administration

The Internet Security and Acceleration (ISA) Server administration COM object model allows you to extend ISA functionality. The administration objects also allow for automation of everything that is done through ISA Management. This means that any task can be automated by an ISA administrator by using the administration objects.

See ISA Administration Scripting for examples of using the objects to automate administrative tasks.

This section contains the following topics:

  • ISA Server Administration Object Model
  • About Administration Scripting
  • Enterprise Edition and Standard Edition


ISA Server Administration Object Model

The following diagram displays the administration COM objects hierarchy. The diagram shows the top of the hierarchy, starting with the root object. Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCArray Object Model

FPCEnterprise Object Model

FPCArrayPolicy Object Model

The following section shows the administration objects derived from the FPCArray object. Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCPolicyElements Object Model

The following diagram shows the administration objects that are derived from the FPCPolicyElements object. Notice that the FPCPolicyElements object is derived from both the FPCArray object and the FPCEnterprise object.

Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCCache Object Model

The following diagram shows the administration objects derived from the FPCCache object. Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCClientConfig Object Model

The following diagram shows the administration objects derived from the FPCClientConfig object. Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCEnterprisePolicies Collection Object Model

The following diagram shows the administration objects derived from the FPCEnterprisePolicies collection. Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCServers Collection Object Model

The following diagram shows the administration objects derived from the FPCServers collection. Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCCacheConfiguration Object Model

The following diagram shows the administration objects derived from the FPCCacheConfiguration object.

FPCFirewallSessions Object Model

The following diagram shows the administration objects derived from the FPCFirewallSessions collection. Shaded boxes represent collections and non-shaded boxes represent objects.

FPCWebSessions Object Model

The following diagram shows the administration objects derived from the collection. Shaded boxes represent collections and non-shaded boxes represent objects.

FPCNetworkConfiguration Object Model

The following diagram shows the administration COM objects derived from the FPCNetworkConfiguration object. Shaded boxes represent collections and non-shaded boxes represent objects. Click boxes to move through the entire hierarchy.

FPCRoutingRules Object Model

The following diagram shows the administration COM objects derived from the FPCRoutingRules collection. Shaded boxes represent collections and non-shaded boxes represent objects.

FPCAlerts Object Model

The following diagram shows the administration COM objects derived from the FPCAlerts collection. Shaded boxes represent collections and non-shaded boxes represent objects.


About Administration Scripting

Scripting allows you to use the ISA Server administration objects to access and control policies and configurations for an enterprise or for any ISA array within an organization.

ISA administration scripting has a number of benefits, such as saving time on tasks that are repetitive or need to be carried out on a number of servers or arrays. Administration scripting has other advantages:

Simplifies configuration changes: With ISA you do not need to write code that accesses the Registry or Microsoft® Active Directory™ service because the Save and Refresh methods of the COM objects will save configuration changes for you. The objects thereby provide simple and comprehensive access to ISA configuration. The objects also use Active Directory in Windows® 2000 when available, while hiding the storage implementation details from the developer.

Maintains consistency: ISA object methods that set the values of multiple related properties with one method call will check whether the combinations of property settings are valid, and return errors if the properties are not set correctly. Consistency is maintained because scripts do not assign conflicting property settings.

Ensures that services receive changes: Most ISA administration objects have a Save method that stores changes. Services register to detect and use the new settings. This dynamic configuration allows services to receive notification of the changes without requiring the server to be stopped and restarted. Some changes will not take place immediately. For example, if a user is in an FTP session, revoking that user's FTP privileges will not cancel the current session. However, that user will not be able to request another FTP session.

Allows command-line and Windows scripting: Microsoft Windows Script Host is a language-independent scripting host for Microsoft ActiveX® scripting engines. It allows you to run ISA Server administration scripts from both the Windows desktop and the command prompt. For more information about Windows Script Host, see MSDN.

Real-time administration: You can create scripts that allow you to query and control the real-time state of your ISA Server arrays.

Task scheduling: Using scripts, tasks that must be performed on a regular basis can be scheduled to occur automatically. For example, you could create a script that would automatically back up configuration information.

Scripting interfaces: Scripts can be easily incorporated into HTML pages. By incorporating scripts into an HTML page, you can create a scripting interface to ease administrative tasks.

See Also

Cache Administration, ISA Administration Scripting


Enterprise Edition and Standard Edition

ISA Server Enterprise Edition supports the following functionality, which is not available in ISA Server Standard Edition:

  • Can be deployed in multi-server arrays for better scalability, performance, fault tolerance, and centralized management.
  • Supports two levels of policy management. Array policy can be applied to an entire array of servers. Enterprise policy can be applied to all the arrays in the organization.
  • Has no restriction on number of processors on the ISA Server computer (The Standard Edition is limited to four processors.)

Some properties, methods, parameters, and values are available only with the Enterprise Edition. The reference information in Internet Security and Acceleration Server Reference makes note of each item that is available only for the Enterprise Edition. A list of these items is provided in ISA Management for Standard Edition and Stand-Alone Servers.


Enterprise Management Overview

With ISA Server Enterprise Edition, you can set up ISA Server computers as stand-alone servers or group them into arrays. Arrays include one or more ISA Server computers, all of which share the same configuration. ISA Server extends centralized management for arrays to the enterprise level.

The ISA Server enterprise includes all the arrays in your organization. When you set up the enterprise, you specify the enterprise policy management. You can select a centralized enterprise policy that applies to all arrays in the enterprise or a more flexible policy where each array administrator can define a local policy.

You can create array-level access policies and enterprise-level policies. The enterprise policy can be applied to any array and can be augmented by the array's own policy. This enables administrators at branch and departmental levels to adopt governing enterprise policies.

Note An access policy, which includes Site and Content Rules, Protocol Rules, and IP Packet Filters is represented in the administration COM object model by the FPCArrayPolicy object, which also includes the ISA Web proxy properties.


About the ISA Server Firewall

The Internet Security and Acceleration (ISA) Server 2000 consists of the Firewall service, application filters, the Web proxy service, and Web (ISAPI) filters. An HTTP redirector filter diverts all HTTP requests to the Web proxy service.

The ISA firewall also provides dynamic Internet Protocol (IP) packet filters to evaluate packets, and Secure Network Address Translation (SecureNAT) to enable NAT clients to connect through ISA. Also, ISA Server uses the bandwidth control of Windows® 2000 Quality of Service (QOS) to allow you to manage bandwidth use.

This section includes the following topics:

  • Controlling Outgoing Requests
  • Controlling Incoming Requests
  • IP Packet Filtering
  • Intrusions and Alerts
  • Secure Network Address Translation

The Web proxy service includes the ISA cache, discussed in About the ISA Server Cache.


Controlling Outgoing Requests

One of the primary functions of ISA Server is to connect your local network to the Internet while protecting your local network from malicious content. To facilitate this connectivity, you use ISA Server to create an access policy that permits internal clients access to specific Internet hosts. The access policy, together with the routing rules, determines how clients access the Internet.

When ISA Server processes an outgoing request, it checks routing rules, site and content rules, and protocol rules to determine if access is allowed. A request is allowed only if both a protocol rule and a site and content rule allow the request and if there is no rule that explicitly denies the request.

Some rules can be configured to apply to specific clients. In this case, the clients can be specified either by Internet protocol (IP) address or by user name. ISA Server processes the requests differently, depending on which type of client requests the object and on how you configure ISA Server.

For an outgoing request, rules are processed in the following order:

  1. Protocol rules. First, ISA Server checks the protocol rules. ISA Server allows the request only if a protocol rule specifically allows the request and if no protocol rule specifically denies it.
  2. Site and content rules. Next, ISA Server checks the site and content rules. ISA Server allows the request only if a site and content rule specifically allows the request and if no site and content rule specifically denies it.
  3. IP packet filters. ISA Server then checks if an IP packet filter has been configured to specifically block the request, to determine if the request should be denied.
  4. Routing rules or Firewall chaining configuration. Finally, ISA Server checks the routing rules (if a Web proxy client requested the object) or the firewall chaining configuration (if a SecureNAT or firewall client requested the object) to determine how the request should be serviced.


Controlling Incoming Requests

ISA Server can also make internal servers securely accessible to external clients. You use ISA Server to create a publishing policy to securely publish your internal servers. The publishing policy, which consists of Internet protocol (IP) packet filters, Web publishing rules, or server publishing rules, together with the routing rules, determine how internal servers are published.

You can use one of the following ISA Server rules to publish servers:

  • Web publishing rules to publish Web server content.
  • Server publishing rules to publish content on all other servers located on the internal network.
  • IP packet filters to publish content on servers on a perimeter network (also known as a screened subnet).

When ISA Server processes a request from an external client, it checks IP packet filters, publishing rules, and routing rules to determine if the request is allowed and which internal server should service the request.

For an incoming Web request, rules are processed in the following order:

  1. IP packet filters. If packet filtering is enabled, then if an IP packet filter specifically denies the request, the request is denied.
  2. Web publishing rules. If a Web publishing rules specifically denies the request, then the request is denied.
  3. Routing rules. If a routing rule specifies that the requests be routed to a specific upstream server or an alternate hosted site, then the specified server handles the request. If a routing rule specifies that the requests be routed to the specified server, then the internal Web server returns the object.


IP Packet Filtering

Internet Protocol (IP) packet filtering intercepts and evaluates packets before they are passed to higher levels in the protocols or to an application. This includes every IP packet, including Transmission Control Protocol (TCP) packets, User Datagram Protocol (UDP) datagrams, and other packet types. IP packet filters can be configured so that only specified packets will be passed through the ISA Server. This provides a high level of security for your network. IP packet filtering can block packets originating from specific Internet hosts and can reject packets associated with many common attacks. IP packet filtering can also block packets destined to any service on your internal network, including the Web proxy, Firewall, World Wide Web (WWW), or SMTP services.

With Internet Protocol (IP) packet filters, you can intercept and either allow or block packets destined for specific computers on your corporate network. You can configure two types of static IP packet filters: allow filters and block filters.

Packets that are not specifically blocked are passed to the ISA services at the application level. At the application level, you can create an ISA Server policy, which is a set of rules that specify what communication is allowed. The ISA Server policy also specifies the communication that should be allowed or blocked from reaching the Web proxy and ISA Firewall services. Ports are opened for transmission or reception, and then immediately closed after one of the ISA services closes the connection.

Dynamic Packet Filtering

ISA Server supports inbound and outbound IP packet filtering. ISA Server can dynamically determine which packets can be passed through to the internal network's circuit and application layer services. You can configure access policy rules that open ports automatically only as allowed, then close the ports when the communication ends. This process is known as dynamic IP packet filtering. This approach minimizes the number of exposed ports in either direction and provides a high level of problem-free security for your network.

For many application protocols, such as media streaming, dynamic IP packet filtering provides the most secure method to handle dynamically allocated ports.


Intrusions and Alerts

ISA Server features an intrusion-detection mechanism, identifying when an attack is attempted against your network, and performing a set of configured actions in case of an attack.

To detect unwanted intruders, ISA Server compares network traffic and log entries to well-known attack methods. Suspicious activities trigger alerts, which are a set of configurable actions. Actions include connection termination, service termination, e-mail alerts, and logging.

ISA Server monitors for the following types of attacks:

  • All-port scan attack
  • Enumerated-port scan attack
  • IP-half scan attack
  • Land attack
  • Ping-of-death attack
  • UDP bomb attack
  • Windows out-of-band attack

For more information, see the ISA Server product documentation.


Secure Network Address Translation

Secure network address translation (SecureNAT) is an extension of the Microsoft® Windows® 2000 NAT driver.

NAT substitutes a global IP address, valid on the Internet, for an internal IP address. This substitution allows multiple hosts with private IP addresses to share a single external (public) IP address, yet remain protected by the ISA Server Firewall service.

ISA Server's SecureNAT feature provides a degree of address transparency for networked clients. NAT is based on an Internet Engineering Task Force (IETF) standard, and substitutes a global IP address that is valid on the Internet for an internal IP address. ISA Server enhances the underlying NAT functionality of Windows 2000 by enabling access control for FTP, ICMP, H.323, and PPTP protocols. NAT also enables rerouting HTTP requests, which can then frequently be satisfied by a local cache, as is the case for CERN proxy.

SecureNAT provides Internet connectivity for multiple computers that share a single modem and Internet service provider account. SecureNAT lets multiple hosts connect through a single gateway computer to the public Internet. The SecureNAT feature allows a single dial-up or other connection to the public network to serve the entire network, which then allows access to both the Internet and corporate networks for telecommuting and other purposes. Every host on the private network shares one or more global addresses.

If network settings are configured so that the default gateway is the IP address of an ISA Server computer, the NAT substitutes such a globally valid source IP address for the private IP address of a client that originates an outgoing request. The NAT will substitute in the source address of the ISA Server computer in the data packet, because responses must return to the global ISA Server host IP address.

While SecureNAT's transparency eliminates the need to make settings other than that of the default gateway, it is important to note that SecureNAT will not work for all protocols, such as certain gaming protocols, and new protocols, for which no protocol editors exist.

SecureNAT can be used in conjunction with the ISA Firewall service in the case of applications with Windows Sockets (Winsock) capabilities. There is no need to perform manual configuration of this functionality, because configuration occurs behind the scenes. Since SecureNAT works with the Firewall service, application filters can work as NAT editors, and NAT clients can be managed by the administrator as Firewall service clients would be. This means that the ISA Server rules and policies can apply to NAT clients.

SecureNAT Considerations

While SecureNAT provides transparency without special client configuration or installation of software on the client and even provides automatic setting of default gateways, NAT has the following limitations:

  • Only IP-based (not user-based) policies can be implemented, because the identity of users is not passed to the ISA Server. This limits policies to those based on the IP address of the client.
  • NAT works only for those protocols explicitly supported by NAT and may not be used with the majority of protocols that embed IP addresses within packets.
  • For SecureNAT clients, creating a rule that allows access to all IP traffic is the same as allowing access to all of the protocols that are defined in ISA Server. This is not equivalent to allowing access to all IP traffic.

Note to Developers

With SecureNAT, ISA Server extends the underlying NAT functionality of Windows 2000 to the level of the firewall, and thus, to the User mode. An application filter that enables secondary connections for a NAT client takes the place of a NAT editor. Enabling secondary connections for NAT clients through SecureNAT is thus simplified, and you have access to user-mode debugging tools for the development process.

You can develop an application filter that enables secondary connections for a NAT client and that adds functionality equally efficiently for Firewall clients and NAT clients. Alternatively, you can develop an application filter to specifically address the secondary connection needs of NAT clients, enabling them to work with other application filters, such as those that perform content filtering.

If you create an application that uses a proprietary protocol, you can create an application filter that will enable SecureNAT clients to use that application.

Because SecureNAT functions in User mode and is an integral part of ISA, ISA policy can be applied to NAT clients. With SecureNAT, you can control access to FTP, Streaming Media protocols, and Windows NetMeeting® for H.323. ISA Server's SecureNAT also permits you to reroute HTTP requests, which can then frequently be fulfilled by a local cache. This enhancement boosts HTTP performance and lowers bandwidth requirements.


About the ISA Server Cache

Internet Security and Acceleration (ISA) maintains a centralized cache of frequently requested Internet objects that can be accessed by all ISA Server clients. ISA also allows distributed content caching among multiple ISA hosts. Distributed caching may be implemented with arrays, chains, or a combination of both.

This section includes the following topics:

  • How ISA Server Caching Works
  • ISA Server Caching Mechanism
  • Cache Administration


How ISA Server Caching Works

The Web proxy service of ISA Server maintains a cache of Web objects and attempts to fulfill Web requests from the cache. If the request cannot be fulfilled from the cache, the ISA Server computer initiates a new request on behalf of the client. Once the remote Web server responds to the ISA Server computer, the ISA Server computer caches the response to the original client request and sends a response to the client.

ISA Server supports forward caching, used for outgoing requests, and reverse caching, used for incoming requests. Clients in both forward caching and reverse caching benefit from the full gamut of ISA Server caching features.

ISA Server includes an Hypertext Transfer Protocol (HTTP) redirector filter, which allows Firewall and secure network address translation (SecureNAT) clients to also benefit from the caching features. When the HTTP redirector is enabled, Web requests from Firewall and SecureNAT clients can also be cached.

If you installed ISA Server in Firewall mode, ISA Server does not maintain a cache.

ISA Server analyzes routing rules, cache configuration, and existing cache content to determine if an object should be retrieved from the cache.

First, if the user request is allowed, ISA Server checks if the object exists in its cache. If the request is made to an array of ISA Server computers, then the Cache Array Routing Protocol (CARP) algorithm is used to determine which server's cache should be checked. If the object is not in the cache, then ISA Server checks the routing rule's action, to determine how to route the request. If the object is in the cache, then ISA Server performs the following steps:

  1. ISA Server checks if the object is valid. The object is considered invalid if one of the following conditions is true:
    • The time-to-live (TTL) that is specified in the source has expired.
    • The TTL that you configured in a scheduled cache content download job has expired.
    • The TTL that you configured for the object has expired.

    If the object is valid, ISA Server retrieves the object from the cache and returns it to the user.

  2. If the object is invalid, then ISA Server checks the applicable routing rule. If you configured the routing rule cache properties to return any version of the object, then ISA Server retrieves the invalid object from the cache.
  3. If the routing rule is configured to route the request, then ISA Server determines whether to route the request to the upstream server or to the requested Web server.
  4. If the routing rule is configured to route the request to the Web server, then ISA Server checks if the Web server is accessible.
  5. If the Web server is not accessible, then ISA Server checks if you configured the server to return expired objects from the cache. If you instructed the server to return the expired object as long as the specific expiration time did not pass, then the object is returned from the cache to the user.
  6. If the Web server is available, ISA Server determines if the object is cacheable and if you configured the routing rule's cache properties to cache the response. If so, then ISA Server caches the object and returns the object to the user.


ISA Server Caching Mechanism

When you configure a drive for caching, ISA Server creates a cache content file on that drive with the .cdat extension.

There is a cache content file for each 10 GB of space on a disk, to the maximum that you dedicated for the cache. For example, if you allocate 12 GBs of disk space on a particular drive, ISA Server creates two cache content files. The first file will be 10 GBs and the second file will be 2 GB.

As objects are cached, ISA Server appends them to the cache content file. If the cache content file is too full to hold a new object, ISA Server removes older objects from the cache, by using a formula that evaluates age, how often the object is accessed, and size.

Warning Do not modify or delete the cache content files.

This section contains the following topics:

  • RAM Caching
  • Cache Array Routing Protocol


RAM Caching

In ISA Server, cached pages are stored immediately in memory to be accessed by clients. A "lazy-writer" approach is used to write the pages to a disk. This approach results in faster cache-availability of the page. There is no direct mechanism for checking whether a page has been cached or written to the disk.

The ISA cache approach results in improved cache performance. If the system stops responding, Web objects stored in memory that have not yet been written to a disk must be obtained from the Internet.


Cache Array Routing Protocol

ISA Server uses the Cache Array Routing Protocol (CARP) to provide seamless scaling and efficiency when using multiple ISA Server computers that are arrayed as a single logical cache. CARP uses hash-based routing to determine the best path through an array to resolve a request. The request resolution path is based upon a hash of array member identities and Uniform Resource Locators (URLs). For any given URL request, the browser or downstream proxy server will know exactly where in the array the information will be stored. The request resolution path indicates if the information was already cached from a previous request, or has to be obtained from the Internet and then cached for future requests.

CARP provides powerful benefits:

  • Because CARP determines the best request resolution path, there is no query messaging between proxy servers, as is found with conventional Internet Cache Protocol (ICP) networks. By doing this, CARP avoids the heavier query congestion that normally occurs with a greater number of servers.
  • CARP eliminates the duplication of contents that otherwise occurs on an array of proxy servers. With an ICP network, an array of five proxy servers can rapidly evolve into duplicate caches of the most frequently-requested URLs. The hash-based routing of CARP keeps this from happening by allowing all five ISA Server computers to exist as a single logical cache. The result is a faster response to queries and a far more efficient use of server resources.
  • CARP has positive scalability. Due to its hash-based routing and its resultant independence from peer-to-peer pinging, CARP becomes faster and more efficient as more proxy servers are added. ICP arrays must conduct queries to determine the location of cached information, an inefficient process that generates extraneous network traffic. ICP arrays have negative scalability: the more servers added to the array, the more querying required between servers to determine location.
  • CARP automatically adjusts to additions or deletions of servers in the array. The hash-based routing means that, when a server is either taken offline or added, only minimal reassignment of URL caches is required.
  • CARP ensures that the cache objects are either distributed evenly between all servers in the array or by the load factor that you configure for each server.

How CARP Works

The CARP process provides efficient routing for requests.

  1. All servers are tracked through an array membership list, which is maintained in Active Directory. Array members are notified when servers are added or removed from the array.
  2. Periodically, the Web proxy client or a downstream server polls and, if necessary, updates the array membership list.
    • Web proxy clients send an array.dll?Get.Routing.Script request to the member server.
    • Downstream servers send an array.dll?Get.Info.v1 request to the member server.
  3. When requesting an object, the client or downstream server uses the membership list, together with a hash function it computes for the name of each requested URL, to determine which server should service the request.
  4. The hash value of the URL is combined with the hash value for each ISA Server. The URL+ISA Server hash that comes up with the highest value becomes "owner" of the information cache.
  5. The server checks if it should handle the request. If not, then it sends the request to another member server, specifying that server's intra-array IP address. The sending member provides its authentication information to the receiving member. In a publishing scenario, it also provides the GUID of the publishing rule.
  6. Once a server has been selected to handle the request, it does so, applying the ISA rule if necessary.

The result is a location for all cached information, meaning that the Web browser or downstream server can know exactly where a requested URL is either already stored locally or will be located after caching. Because the hash functions used to assign values are so numerous, the load is statistically distributed and balanced across the array.

The request resolution path that CARP provides means that there is no need to maintain massive location tables for cached information. The browser simply runs the same math function across an object to determine where it is.

Because ISA Server computers in an array may have different hardware and some may be more powerful than others, you may want to divide the cache load accordingly. For this reason, you can configure the CARP functions, specifying the load factor for any given server in the array.

Furthermore, you can configure CARP differently for incoming and outgoing Web requests. For example, CARP can be enabled for all outgoing Web requests, and disabled for all incoming Web requests.


Cache Administration

The ISA administration COM objects allow you to administer the cache programmatically, automate administrative tasks related to the cache, and extend cache performance by using the FetchUrl method. An introduction to FetchUrl is provided in Extending the Cache.

For more information regarding cache administration, see Managing the ISA Server Cache.


About ISA Server Rules

You can configure ISA Server to meet your specific security and performance needs by defining and configuring rules that determine whether users, computers, or applications are granted access to computers in your network and on the Internet. ISA Server allows you to define several types of rules:

  • Access policy rules, which include IP Packet Filters, protocol rules, and site and content rules.
  • Bandwidth rules.
  • Publishing policy rules.

When an internal client requests an Internet object, ISA Server processes the rules to determine if the request is allowed.

Similarly, when an external (Internet) client requests an object from an internal server, ISA Server processes the rules to determine if the request is allowed.


Access Policy Rules

Access policy rules include:

  • IP Packet Filters
  • Protocol Rules and Site and Content Rules


IP Packet Filters

The packet filtering feature of ISA Server allows you to control the flow of Internet protocol (IP) packets to and from ISA Server. When you enable packet filtering, all packets on the external interface are dropped unless they are explicitly allowed, either statically by IP packet filters or dynamically by access policy or publishing rules.

Even if you do not enable packet filtering, communication between your local network and the Internet is allowed only when you explicitly configure rules that permit access.

In most cases, it is preferable to open ports dynamically. Therefore, it is usually recommended that you create access policy rules to allow internal clients access to the Internet or publishing rules to allow external clients access to internal servers. This is because IP packet filters open the ports statically, but the access policy and publishing rules open the ports dynamically (as a request arrives). For example, suppose you want to grant all internal users access to Hypertext Transfer Protocol (HTTP) sites. You should not create an IP packet filter that opens port 80. Rather, you should create the necessary site and content rule and protocol rule that allow this access.

You can create IP packet filters that filter packets based on service type, port number, source computer name, and destination computer name. IP packets filters are static - communication through a specific port is either always allowed or always blocked. Allow filters are exception filters in that all packet types are blocked except for those you specify. If you do not have a packet filter activated for a specific port, then the service cannot listen on that port unless the port is opened dynamically.

Block filters close the specified ports. You can create and configure block filters to further define the traffic allowed through the ISA Server computer. For example, you can create an allow filter that allows Transmission Control Protocol (TCP) traffic on port 25 between all internal and external hosts, thus activating Simple Mail Transfer Protocol (SMTP) communication. You can then limit access, creating a block filter that blocks a set of external hosts, such as potential intruders, from sending TCP packets to port 25 on your ISA Server computer.


Protocol Rules and Site and Content Rules

Protocol rules define which protocols can be used for communication between the local network and the Internet. Protocol rules are processed at the application level. For example, a protocol rule might allow clients to use the HTTP protocol.

Site and content rules define what content on which Internet sites can be accessed by clients behind the ISA Server computer. Site and content rules are processed at the application level. For example, a site and content rule might allow clients to access any destination on the Internet.

When you install ISA Server, you specify the installation mode: firewall, cache, or integrated. The following table lists which access policy rule types are available for each mode.

Rule type | Firewall | Cache | Integrated
Site and content rules | Yes | Yes | Yes
Protocol rules | Yes | Yes, for HTTP, File Transfer Protocol (FTP), and Secure HTTP (HTTPS) | Yes


Bandwidth Rules

Bandwidth rules determine what connection gets priority over another. ISA Server bandwidth control does not limit how much bandwidth can be used. Rather, it informs the Windows 2000 quality of service (QoS) packet scheduling service how to prioritize network connections. Any connection that does not have an associated bandwidth rule will get a default scheduling priority. On the other hand, any connection with an associated bandwidth rule will be scheduled ahead of default scheduled connections.

When you install ISA Server, you specify the installation mode: firewall, cache, or integrated. Bandwidth rules are available in all installation modes.


Publishing Policy Rules

You can use ISA Server to configure a publishing policy, which consists of server publishing rules and Web publishing rules. Publishing policy is created on the array level, rather than on the enterprise level.

Server publishing rules filter all incoming requests. Server publishing rules map incoming requests to the appropriate servers behind the ISA Server computer.

Web publishing rules map incoming requests to the appropriate Web servers behind the ISA Server computer.

When you install ISA Server, you specify the installation mode: firewall, cache, or integrated. The following table lists which publishing policy rule types are available for each mode.

Rule type | Firewall | Cache | Integrated
Web publishing rules | No | Yes | Yes
Server publishing rules | Yes | No | Yes


About Authentication in ISA Server

The access policy and publishing rules of ISA Server can be configured to allow or deny a set of computers (client address sets) or a group of users from accessing specific servers. If the rule applies specifically to users, then the ISA Server checks the Web request properties for listeners on the array to determine how the user should be authenticated.

You can configure incoming and outgoing Web request settings so that users must always be authenticated by ISA Server before processing rules. This ensures that requests are allowed only if the user making the request is authenticated.

This section includes the following topics:

  • Authentication Methods
  • Rules and Authentication
  • ISA Server and Secure Sockets Layers


Authentication Methods

You can configure which authentication method to use. You can configure different authentication methods for incoming Web requests and for outgoing Web requests.

ISA Server supports the following authentication methods: basic authentication, digest authentication, Integrated Windows authentication, and client certificates and server certificates.

Microsoft Internet Explorer 5 supports all the authentication methods. Other Web browsers may support only the basic authentication method. Be sure that the client Web browsers can use at least one of the authentication methods that you specify in an array's incoming Web request and outgoing Web request properties. Otherwise, the client will not be able to access the requested object.


Rules and Authentication

When a Firewall client requests content which is not Hypertext Transfer Protocol (HTTP), ISA Server determines if any rules have been configured to apply to specific users or groups. If so, then ISA Server requires that the client authenticate itself, so that ISA Server can determine if the rule applies to the client requesting the object.

When a Web proxy or Firewall client requests HTTP content, ISA Server checks the rules to determine if a specific rule allows anonymous users access (either because it applies to all users, or it applies to a client address set that includes the IP address of the client). If so, then the request is allowed. Otherwise, if no rule has been configured to allow anonymous users access, ISA Server requires that the client authenticate itself, to determine if a rule applies to the specific, authenticated user.

In other words, when a client requests HTTP content, authentication information is not passed to the ISA Server, unless ISA Server requires it. This happens when the Web proxy service must identify the user to allow the request.

You can configure ISA Server to always require authentication for Web requests by using the FPCWebRequestConfiguration.AlwaysAuthenticate property.

For Firewall clients, HTTP requests are passed to the HTTP redirector, if the filter is enabled and configured. In this case, the Firewall client's authentication information is not passed to the Web proxy service and ISA Server treats the request as if it were from an unauthenticated user. If ISA Server cannot pass the request from unauthenticated user, then the request will be denied, because ISA Server will not ask for authentication.

Authentication Example

Suppose you configure ISA Server with the following rules:

  1. A protocol rule that allows everyone to use all protocols.
  2. A site and content rule that allows everyone access to all sites.
  3. A site and content rule that denies access to user John.

The first two rules allow access to all requests from anonymous users. The third rule will be enforced, that is, John's request will be denied, only if ISA Server requires that John authenticate himself. For example, consider the following scenarios:

  • John's computer has Firewall client installed. John requests non-HTTP content. John's request will be denied because the ISA Server Firewall service requires authentication; the third rule is therefore enforced.
  • John's computer is configured as a Web proxy client. John requests HTTP content, John's requests will be allowed because ISA Server does not require authentication; the third rule is therefore not enforced.
  • John's computer has Firewall client installed. John requests HTTP content. John's request will be allowed because ISA Server does not require authentication; the third rule is therefore not enforced.

To enforce the third rule for all Web requests, configure the array option to ask unauthenticated users for identification. John's request will be denied in all the scenarios previously listed.


ISA Server and Secure Sockets Layers

In ISA Server you can use Secure Sockets Layer (SSL) security features for authentication. Certification is used in two ways when a client requests an object from a server:

  • The server authenticates itself by sending a server certificate to the client.
  • The server requests that the client authenticate itself. In this case, the client must present an appropriate client certificate to the server.

SSL authenticates by checking the contents of an encrypted digital identification submitted by the user's Web browser during the logon process. Server certificates contain identifying information about the server. Client certificates usually contain identifying information about the user and about the organization that issued the certificate. Users obtain client certificates from a trusted external organization.

Client Certificate

If client certificate is the selected authentication method, then ISA Server requests a client certificate from the client before allowing the request.

The ISA Server computer receives the request and sends a server certificate to the client. The ISA Server computer thereby identifies itself as the SSL Web server. The client receives the certificate, and verifies that the certificate indeed belongs to the ISA server computer.

The client then resends its request to the ISA Server computer. However, the ISA Server computer requires a certificate from the client that must have been previously issued. The ISA Server computer verifies that the certificate indeed belongs to a client that is allowed access.

The client certificate should be installed in the Microsoft Web Proxy Service certificate store on the ISA Server computer. The certificate should be mapped to the appropriate user account.

ISA Server can present client certificates only in SSL bridging scenarios.

Server certificate

When a client requests SSL objects from a server, it requests that the server authenticate itself. If the ISA Server terminates an SSL connection, then the ISA Server will have to authenticate itself to the client. You must configure and specify a server-side certificate to use when authenticating ISA Server to the client.

The server certificate should be installed in the Local Computer certificate store on the ISA Server computer. The certificate name should be identical to the name of the ISA Server (for outgoing Web requests) or to the name of the published Web servers (for incoming Web requests)


About ISA Server Services

ISA Server acts as a gateway to the Internet, implementing security in three security layers: IP packet filtering, application layer, and circuit layer. ISA Server's multilayered approach is made possible by the services included with ISA Server:

  • ISA control service. This service is responsible for the IP packet filter (enabling, opening static filters, logging), restarting the other services as necessary, generating alerts, running actions and other functions.
  • Scheduled cache content download service.
  • Web proxy service. The Web proxy service is implemented at the application level, and works only with application protocols.
  • Firewall service. The Firewall service is implemented at the circuit level.

All the services work with dynamic IP packet filtering, to provide a complete security model.

This section contains the following sections:

  • About the ISA Control Service
  • About the Scheduled Cache Content Download Service
  • About the Firewall Service
  • About the Web Proxy Service


About the ISA Control Service

The ISA control service controls the following ISA functions:

  • IP packet filters, including enabling filters, opening static filters, and logging filters.
  • Restarting other ISA services as necessary.
  • Generating alerts and running actions.
  • Synchronizing each server with the server array. The ISA control service updates the client configuration files (msplat.txt and mspclnt.ini) and deletes unused log files.
  • Restarting other ISA services when certain changes are made through ISA Management, as described in the ISA Server product documentation.

You cannot use ISA Management to stop or start the ISA Server Control Service. To stop the service, type the following at a command line:

net stop mspadmin

If you stop the ISA Server Control Service, all the other ISA Server services will also be stopped.


About the Scheduled Cache Content Download Service

ISA Server further extends caching performance with a customizable scheduled downloading feature. The ISA Server scheduled content download feature enables you to download HTTP content directly to the ISA Server cache, upon request or as scheduled. This enables you to update the ISA Server cache with HTTP content that you anticipate will be requested by clients in your organization.

You can configure which content ISA Server should precache and schedule when the content should be cached, available for access directly from the ISA Server cache rather than from the Internet. By monitoring and analyzing Internet access, you can determine which Internet objects will be needed and when. Then you can use scheduled downloading to prepare the ISA Server cache accordingly.

You can use scheduled content downloading to schedule downloads of HTTP files from a Web site to a local cache. You can download a single URL, multiple URLs, or an entire Web site according to a schedule you specify.

Note Sites that contain pop-ups, such as those that ask for credentials, or offer installation of language packs, cannot be downloaded by the scheduled cache download service. Also, Web sites that expect cookies when a client requests a page cannot be precached.


About the Firewall Service

The Firewall service is a generic, circuit-level proxy for Windows Sockets (Winsock) applications. The ISA Firewall service makes Telnet, e-mail, news, Microsoft NetShow®, RealNetworks RealAudio, Internet Relay Chat (IRC), and other Winsock-compatible client applications perform as though they were directly connected to the Internet. The client application makes Winsock application programming interface (API) calls to communicate with an application running on an Internet-based host. The ISA Firewall service redirects the necessary functions to the ISA Server computer, thus establishing a communication path from the internal application to the Internet application through the ISA Server computer. This redirection eliminates the need for a specific gateway for each protocol, such as Network News Transfer Protocol (NNTP), Simple Mail Transfer Protocol (SMTP), Telnet, or File Transfer Protocol (FTP). The ISA Firewall service allows applications with no built-in support for a proxy to benefit from proxy service without using the protocols.

The Firewall service runs as a stand-alone service on Windows 2000. It establishes gateway connections between the Windows Sockets (Winsock) applications on the client and the Internet host. The local network remains secure, because communication is channeled through the ISA Server. The Firewall service can be enhanced by using application filters.

This section contains the following topics:

  • How the Firewall Service Works
  • About the Firewall Client
  • Application Filters


How the Firewall Service Works

The Firewall client captures an API call and redirects it to the Firewall service, which makes the actual call. That is, there are actually two connections: one on the private network from the client to the ISA server and one over the Internet from the Internet host to the ISA server.

The Firewall service consists of two parts: a dynamic-link library (DLL) running on the Firewall client and a service running on the ISA Server computer.

When ISA Firewall client software is installed on the computer, it installs two .dll files. The files intercept Winsock API calls from applications on the client and forward them to the ISA Server computer by using a control channel.

The control channel manages remote Winsock messages, and is designed to do the following:

  • Deliver the Local Address Table (LAT) to the client. The LAT determines whether a destination is on the local network.
  • Establish TCP connections from the client to the ISA Server. This channel is used to build the virtual connection while attempting to connect with a remote application.
  • Furnish UDP communications to and from the ISA Firewall client and with the ISA Server.

The ISA Firewall client .dll is initialized when the first Winsock connection is attempted. Then a control channel with the ISA Firewall service is established, and then designated as active through the channel. Finally, the LAT is copied from the server to determine which networks are on the Internet and which are local.

Note The Firewall service of ISA Server makes use of a Windows Sockets 2.0 layered service provider (LSP) architecture. For more information on LSPs, see MSDN.


About the Firewall Client

You can install Firewall client software on client computers that run Microsoft® Windows® Millennium Edition (Me), Windows 95, Windows 98, Windows NT® 4.0, or Windows 2000. 16-bit Winsock applications are supported, but only on Windows 2000 and Windows NT 4.0.

The Firewall client component is layered on top of the original Winsock implementation. In platforms that support Winsock 2.0, the client is a layered service provider (LSP). On other platforms, the client setup application renames the original Winsock DLL (wsock32.dll) and installs its own implementation of wsock32.dll.

The Firewall client communicates with the Firewall service by using a dedicated connection called the Firewall service control channel. The control channel connection is established the first time it is needed.

When a client application calls a Winsock function, the client DLL intercepts the call and decides based on the specified request, and the firewall service configuration files, whether the call is local or remote. Local calls are passed to the original Winsock implementation. Remote calls are redirected to the firewall service.

When a function call is redirected to the proxy, the client component sends a request through the control channel to the Firewall service and waits for a response. The Firewall service checks the request against the ISA Server policy, processes the request on behalf of the client, and returns a reply through the control channel. The reply is then processed by the Firewall client, and translated to a Winsock error code in case of failure.

Note The remote Firewall client software supports basic Winsock 1.0 and Winsock 2.0 functionality. However, the following limitations should be noted:

  • Overlapped I/O on WSARecvFrom — The Winsock API will work, but for a remote socket, the from address that the application will receive is the address of the firewall service's internal socket. However, using a blocking or non-blocking recvfrom, the application will see the actual from address of the Internet host that originally sent the packet.
  • Winsock QoS — ISA installs an LSP that supports Quality of Service (QoS) requests. However, for connections made through the Firewall service, Resource Reservation Protocol (RSVP) reservations will not pass through the service.
  • Winsock Name Service Functions are limited — WSALookupService{Begin/Next/End} are implemented, but only resolve queries that would translate into queries by using the gethostbyname, gethostbyaddr, getservbyport, or getservbyname functions.


Application Filters

Application filters are extensions of the Firewall service. These filters register for and process Firewall service events. By exposing its COM interfaces to developers, ISA Server allows them to extend its security and functionality. Developers can use these interfaces to extend the security and access control for Firewall service, and to create protocol-specific application filters. These can share the architecture, access control, and administration of the Firewall service. Use of these interfaces is described in Developing Application Filters. Specifically, the interfaces allow a filter to:

  • Receive notifications of special events; for example, when a user connects to a certain remote port.
  • Allow or deny user access to certain operations; for example, binding to a particular port.
  • Examine and possibly modify data that flows through the firewall; for example, to perform virus checking.
  • Initiate network operations (proactive caching) through dynamic IP packet filtering.
  • Seamlessly integrate with ISA Management.

See Also

Developing Application Filters, Filter Interfaces


About the Web Proxy Service

The Web proxy service (W3proxy) is a Windows 2000 service that supports requests from any browser that conforms to standards of the Conseil Europeen pour la Recherche Nucleaire (CERN). The Web proxy service allows Web access to nearly every desktop operating system, including Windows NT, Windows 95, Windows 98, Windows 2000, Macintosh, and UNIX.

The Web proxy service works at the application level on behalf of an HTTP client requesting an Internet object retrievable through one of the protocols supported by the Web proxy service: FTP, HTTP, HTTPS, and Gopher. Web proxy protects all Web browser access. The Web proxy service operates with a Web proxy client, which can be any client computer that uses CERN-compliant applications and is configured to use the Web proxy service of ISA Server.

Unlike Microsoft Proxy Server 2.0, which implemented the Web proxy as a Web (ISAPI) filter loaded by the local Internet Information Services (IIS) Web server, Web proxy now runs as a Windows 2000 process (W3proxy.exe). The process can be initialized by starting the Web proxy service. IIS Server can be installed on an ISA Server computer, but this is not required. For more information on IIS and ISA, see Internet Information Services Separation.

You can use the secure Web publishing feature of ISA in conjunction with Internet Information Services (IIS) or other Web servers to publish to the Internet without compromising the security of your internal network. ISA uses Secure Web publishing and reverse hosting to send requests to Web-publishing servers connected behind the ISA proxy computer. ISA server's Web proxy (W3proxy) service supports the use of Secure Sockets Layer (SSL), and also supports Web (ISAPI) filters.

The Web proxy service includes the ISA cache, described in About the ISA Server Cache.


Web Proxy Service Clients

Web proxy clients (typically browsers) must be specifically configured to use the ISA Server. When a user requests a Web site, the browser parses the URL. If the name contains "dots" such as a Fully Qualified Domain Name (FQDN), the browser considers the destination to be remote and sends the HTTP request to the ISA Server for processing.


Web (ISAPI) Filters

Web (ISAPI) filters detect and process HTTP events, and can extend the functionality of the Web proxy service. By using the Internet Server application programming interface (API), ISA supports the Web filter extensibility model, which lets third-party developers examine and change the HTTP request and response flow. ISA does not support ISAPI extensions.

For more information about ISA support of Web filters, see Developing Web (ISAPI) Filters for ISA.


Internet Information Services Separation

Unlike Microsoft Proxy Server 2.0, which implemented the Web proxy service as an ISAPI filter that was loaded by the local IIS Web server, the Web proxy service now runs as a Windows 2000 service named W3proxy. The process can be initialized by starting the Web proxy service. IIS Server can be installed on an ISA Server computer but it is not required.

The incoming Web request and outgoing Web request properties can now run on different TCP ports. For example, by default, ISA Server listens for outgoing Web requests on TCP port 8080, while ISA Server listens for incoming Web requests on TCP port 80. In this way, ISA Server ensures that outgoing Web requests do not interfere with Web publishing on port 80.

If IIS Server is installed on the ISA Server computer, it must be configured to not use the ports that ISA Server uses for outgoing Web requests (by default, 8080) and for incoming Web requests (by default, 80). For example, you can change IIS Server to listen on port 81. Then you can configure the ISA Server computer to direct the incoming Web requests to port 81 on the local IIS Server.

If there is a conflict between ports used by ISA Server and those used by IIS Server, the setup program will stop the IIS publishing service. You can then change IIS Server to listen on a different port and restart the IIS Server publishing service.


About ISA Server Clients

ISA Server supports three types of clients:

  • Firewall clients are client computers that have Firewall Client installed and enabled.
  • Secure network address translation (SecureNAT) clients are client computers that do not have Firewall Client installed.
  • Web proxy clients are any client Web application configured to use ISA Server.

The following table compares the ISA Server clients.

Feature | SecureNAT client | Firewall client | Web proxy client
Installation required | Some network configuration changes are required | Yes | No, requires Web browser configuration
Operating system support | Any operating system that supports Transmission Control Protocol/Internet Protocol (TCP/IP) | Only Windows platforms | All platforms, but by way of Web application
Protocol support | Requires application filters for multi-connection protocols | All Winsock applications | Hypertext Transfer Protocol (HTTP), Secure HTTP (HTTPS), File Transfer Protocol (FTP), and Gopher
User-level authentication | Some network configuration changes are required | Yes | Yes
Server applications | No configuration or installation required | Requires configuration file | N/A

Firewall client computers and SecureNAT client computers may also be Web proxy clients. If the Web application on the computer is configured explicitly to use the ISA Server, then all Web requests (HTTP, FTP, HTTPS, and Gopher) are sent directly to the Web proxy service. All other requests are handled first by the Firewall service.

This section contains the following topics:

  • SecureNAT Clients
  • Firewall Clients
  • Web Proxy Clients


SecureNAT Clients

Client computers that do not have Firewall client software are secure network address translation (SecureNAT) clients. SecureNAT clients can benefit from many of the features of ISA Server. This includes most access control features, with the exception of high-level protocol support and user-level authentication.

Although SecureNAT clients do not require special software, you should configure the default gateway so that all traffic destined to the Internet is sent by way of ISA Server, either directly or indirectly, through a router. You can configure clients either by using the DHCP service or manually.

Since requests from SecureNAT clients are essentially handled by the Firewall service, SecureNAT clients benefit from the following security features:

  • Application filters can modify the protocol stream to allow handling of complex protocols. In Windows 2000 NAT, this mechanism is accomplished through the use of NAT editors which are written as kernel-mode NAT editor drivers in Windows 2000.
  • The Firewall service can pass all Hypertext Transfer Protocol (HTTP) requests to the Web proxy service, which handles caching and ensures that site and content rules are applied appropriately.

SecureNAT and Windows 2000 NAT

ISA Server extends the Windows 2000 network address translation (NAT) functionality by enforcing ISA Server policy for SecureNAT clients. In other words, all ISA Server rules can be applied to SecureNAT clients, despite the fact that Windows 2000 NAT does not have an inherent authentication mechanism. (Policies regarding protocol usage, destination, and content type are also applied to SecureNAT clients.)

SecureNAT Clients and Server Publishing

As with Firewall clients, SecureNAT clients can also actually be servers, such as mail servers, which publish information to the Internet. You configure server publishing rules to publish servers as SecureNAT clients.

SecureNAT clients are not supported in cache mode.


Firewall Clients

A Firewall client is a computer with Firewall Client software installed and enabled. The Firewall client runs Winsock applications that use the Firewall service of ISA Server. When a Firewall client uses a Winsock application to request an object from a computer, the client checks its copy of the local address table (LAT) to see if the specified computer is in the LAT. If the computer is not in the LAT, then the request is sent to the ISA Server Firewall service. The Firewall service handles the request, forwarding it to the appropriate destination, as permitted. The Firewall Client software can send Windows user information, which is required for authentication purposes, to the ISA Server.

Setting up a Firewall client does not configure individual Winsock applications. Instead, it uses the same Winsock dynamic link library (.dll) that the other applications use. The Firewall client then intercepts the application calls and decides whether to route the request to the ISA Server computer.

You can install Firewall Client software on client computers that run Windows Millennium Edition (Me), Windows 95, Windows 98, Windows NT 4.0, or Windows 2000. 16-bit Winsock applications are supported, but only on Windows 2000 and Windows NT 4.0.

Firewall clients are not supported in cache mode.


Web Proxy Clients

A Web proxy client is a client computer that has a Web browser application, which complies with Hypertext Transfer Protocol (HTTP) 1.1 and which is configured to use the Web proxy service of ISA Server. Each Web browser is configured through its own user interface.

When you install Firewall Client software, the Web browser settings on the Firewall Client desktop can be configured automatically. Subsequently, you can reconfigure the Web browser clients. You can configure the following Web browser properties:

  • The ISA Server and port to which the client should connect.
  • Automatic discovery settings.
  • The computers that the Firewall client's Web browser should access directly.
  • Backup route, if the ISA Server is unavailable.

When the Firewall Client software is installed, the Web browser on the client computer is configured with those settings.

If Firewall Client is not installed, then the Web browser can be configured manually.


About ISA Server Setup

Information about setup options for ISA Server is of value to vendors who are creating add-ons for ISA Server, and for administrators who are performing administrative tasks by using the ISA administration COM objects.

This section contains the following topics relating to ISA Server Setup:

  • ISA Server Modes
  • Unattended Setup


ISA Server Modes

As part of the user setup process, you can select the Microsoft Internet Security and Acceleration (ISA) mode: firewall, cache, or integrated.

In firewall mode, you can secure network communication by configuring rules that control communication between your corporate network and the Internet. You can also publish internal servers, thereby sharing data on your internal servers with Internet users.

In cache mode, you can improve network performance and save bandwidth by storing commonly-accessed objects closer to the user. You can then route requests from Internet users to the appropriate Web server.

Different features are available for the firewall and cache modes, as shown in the following table. In integrated mode, all of the features are available.

Feature | Firewall | Cache
Enterprise policy | Yes | Yes
Access policy | Yes | Yes, but only for Hypertext Transfer Protocol (HTTP)
Web publishing | Yes | Yes
Server publishing | Yes | No
Packet filtering | Yes | No
Cache configuration | No | Yes
Application filters | Yes | No
Web filters | Yes | Yes
Real-time monitoring | Yes | Yes
Alerts | Yes | Yes
Reports | Yes | Yes
Virtual private networking | Yes | No
SecureNAT client support | Yes | No
Firewall client support | Yes | No
Web proxy client support | Yes | Yes


Unattended Setup

You can install Microsoft Internet Security and Acceleration (ISA) Server by using the unattended server setup command.

Msisaund.ini contains the configuration information that is used by server setup in unattended mode. It has no effect on the standard ISA Server setup. If a value is not specified in this file, a default value is used. The following table describes the entries and values in the Msisaund.ini file of the server.

Section | Entry | Description
[ISA Setup Install] | Install Dir | Specifies the installation directory for ISA Server. If not specified, it defaults to the first disk drive with enough space. The syntax is: Drive:\Folder The default folder is Systemroot\Program Files\Microsoft ISA Server
[ISA Setup Install] | Override Existing Configuration | If set to 0, setup program retains existing configuration set by previous ISA Server installations, ignoring data from the remaining sections of this file. Default is 0. This option does not apply to an upgrade from Microsoft Proxy 2.0.
[ISA Setup Install] | Don't Migrate Proxy 2 Settings | If set to 1, setup will not attempt to migrate the existing configuration when upgrading from Microsoft Proxy Server 2.0. The default value is 0, indicating that setup will try to migrate the existing Microsoft Proxy Server 2.0 configuration.
[Array Membership] | Join existing array | Specifies the name of the array to join. You must import the schema if you specify Join existing array or Create new array and join. For more information, see the ISA Server product documentation. If you don't specify either Join existing array or Create new array and join, the server is set up as a stand-alone server. You cannot specify both Join existing array and Create new array and join. Applies to Enterprise Edition only - ignored by Standard Edition setup.
[Array Membership] | Create new array and join | Specifies the name of a new array to create. The server is joined to the new array. If you don't specify either Join existing array or Create new array and join, the server is set up as a stand-alone server. You cannot specify both Join existing array and Create new array and join. Applies to Enterprise Edition only - ignored by Standard Edition setup.
[Features] | Installation Option | This specifies the mode in which ISA Server will be installed. Possible values are Integrated, Firewall, and Cache. The default is Integrated. For more information, see ISA Server Modes.
[Firewall LAT Config] | Include Ranges From All Cards | If set to 1, treats all network adapter Internet Protocol (IP) address ranges as being on the internal network. Assumes a dial-up modem connection to the Internet.
[Firewall LAT Config] | Include Private Ranges | If set to 1, treats all network adapter IP address ranges as being on the internal network. Assumes a dial-up modem connection to the Internet.
[Firewall LAT Config] | Range1,Range2... | Defines local address table (LAT) IP ranges specifically. Syntax is Range1=x.x.x.x. Range2=y.y.y.y. If you install ISA Server in cache mode, then you should omit the [Proxy Setup LAT Config] section. If you include this section, then at least one entry must be specified in the [Proxy Setup LAT Config] section, otherwise setup fails.
[Cache Config] | Drive=drive size_min size_max | Specifies the disk drives to be used for caching. You can specify one or more drives to use for caching. The default size for both min_size and max_size is 100. If not specified, it defaults to the first NTFS file system partition large enough for adequate caching. The drive specified must have at least one NTFS partition, otherwise setup fails. If the amount of available space is lower that min_size, setup fails. If the maximum size that is specified exceeds the available space, the cache size is set to the size of the available space. If you install ISA Server in firewall mode, then you should omit the [Proxy Setup Cache Config] section.
[Cache Config] | Enable Cache={1,0} | Specifies whether caching is enabled. If set to 1, caching is enabled. If set to 0, caching is disabled. Default is 1; that is, caching is enabled when this option is not set.

To Run Unattended Setup

  1. Create a file called MsISAund.ini in the root directory of the first fixed drive computer on which you run unattended setup.
  2. At a command prompt, type

    Path\Isa\Setup /qt /k"CD Key" [/Q [0|1|T] [/R] [/U]

Parameters

Path
The path to the Microsoft Internet Security and Acceleration (ISA) Server installation files. The path may be the root folder of the ISA Server CD-ROM or a shared folder on your network that contains the ISA Server files.
CD Key
The CD key, as it appears on the back cover of the ISA Server CD-ROM.
/Q [0|1|T]
Performs unattended setup. If you specify 0, the exit dialog box displays when Setup completes. If you specify 1, the exit dialog box is not displayed. If you specify T, no dialog boxes are displayed.
/R
Performs unattended reinstallation.
/U
Performs unattended uninstallation.

Notes

  • The local address table (LAT) section of Msisaund.ini must specify the Internet Protocol (IP) address of at least one of the internal address cards; otherwise, Setup fails.
  • The Msisaund.ini file must be created in the root directory of the first fixed drive of the computer on which you run unattended setup.
  • If Setup does not find the Msiasund.ini file in the root directory of the first fixed drive, then it looks for the file in the path in which setup is running. The path can be a directory on the local computer or a shared network folder.


Using Internet Security and Acceleration Server

Microsoft® Internet Security and Acceleration (ISA) Server 2000 is a platform that third-party developers can extend by creating components that work with ISA, such as application filters, ISA Management, and Web (ISAPI) filters. For example, a vendor may develop an application filter that scans for viruses. The filter configuration information should be included with ISA configuration information. When ISA is backed up, the virus-scanning filter configuration data is also backed up. The mechanism for integrating third-party data into ISA is the FPCVendorParametersSets collection.

Developers can also create Microsoft Management Console (MMC) extension snap-ins for components designed to work with ISA, so that relevant property pages will be integrated into ISA Management.

Administration Resources

ISA provides extensive support for administration of ISA arrays, either using ISA Management, as described in the product documentation, or through administration scripting.

Source Files and Samples Provided with ISA

The Msfpccom.idl source file contains the definitions of all ISA administration COM objects. In Visual Basic, you access the administration COM objects through the FPCLib type library. The Wspfwext.idl source file contains the definitions of all ISA Firewall interfaces.

Within the ISA Software Development Kit (SDK), the following topics contain example code that can be copied from the text:

  • Configuring arrays
  • Configuring Destination Sets
  • Configuring Schedules
  • Restricting Site Access
  • Restricting Use of a Protocol
  • Preventing Access in a Web Publishing Scenario
  • Adding Internet Access for New Users
  • Scenarios
  • Adding a Custom Event and Alert

ISA Server Script Samples on CD-ROM

In addition to the example code in the SDK, the following samples are on the ISA Server CD-ROM in the sdk\samples\Admin\Scripts folder. The file name of each sample is listed in the Samples column. A brief description and the language extension are also provided. See Script Samples for more detailed descriptions.

Samples | Description | Language
Add_Dod | Shows how to add a new Dialup Entry. | VBScript
AddDeniedMethod | Shows how to add a denied HTTP method. | VBScript
AdditionalKey | Demonstrates the use of the additional key. | VBScript
AddLATEntry | Shows how to add an IP range to the array LAT. | VBScript
AddScheduledContentDownload | Adds a scheduled content download job. | VBScript
ApplicationFilterList | Lists the Application Filters installed on the ISA server. | VBScript, JScript
CacheSettings | Displays array cache settings. | VBScript, JScript
ConstructLAT | Shows how to construct the LAT of an array based on its network interface cards (NICs). | VBScript, JScript
DeleteURL | Causes the Web proxy service to delete a Web object from the ISA cache. | VBScript
DisableScheduledContentDownload | Disables ScheduledContent Download on given days for a given array. | VBScript
EnterpriseDestination | Adds a new Destination Set to the Enterprise, sets the array policy to use Array And Enterprise Policies, and configures the new rule to use the Enterprise Destination. | VBScript
FetchUrl | Causes the Web proxy service to fetch an object and store it in the cache. | VBScript
FindScheduledContentDownload | Receives an array name and a URL and checks if any scheduled content download job includes that URL. | VBScript
ListDeniedMethods | Lists the denied HTTP methods for an array. | VBScript
ListServers | Lists servers in a given array. | VBScript, JScript
SetCache | Sets the cache. | VBScript
SetDefaultApplicationSettings | Demonstrates how to add client settings. | VBScript
SetUpstreamRouting | Shows how to set up upstream routing to another server. | VBScript
ShowAllProtocolRules | Lists all protocol rules of an array. | VBScript, JScript
ShowAllRoutingRules | Lists all routing rules of an array. | VBScript
StaticFilter | Demonstrates how to create a static packet filter, which allows NTP communication with the ISA Server computer. NTP uses the UDP protocol and Port 123. | VBScript

Note The JScript samples have limited functionality compared to the corresponding VBScript samples. The major difference is that JScript will always use the first array in a network, whereas VBScript will ask the user for the array name.

ISA Application Filter Samples on CD-ROM

The following application filter samples are on the ISA CD-ROM in the sdk\samples\application_filters folder. The file name of each sample is listed in the Samples column. The samples are written in C++. For more details regarding the samples, see Sample Filters.

Samples | Description
Connector | A console application that emulates an application protocol (works with ConnectorFilter).
ConnectorFilter | Enables a complex protocol that requires secondary connections on random ports (works with Connector application).
DbgDump | Registers for notifications on all possible events, installs data filters on all connections, and outputs information about the events to the debugger.
Exeblock | Blocks all executable files unless a protocol rule is defined allowing a specific user to receive executable files.
Serversplit | Demonstrates the use of connection emulation for inbound connections.
SMTPFLTR | Captures and analyzes data sent by external clients that use the SMTP protocol.
Socks4a | Demonstrates the use of SOCKS protocol version 4/4A.
Socks5 | Demonstrates the use of the SOCKS 5 protocol.

ISA Web Filter Samples on CD-ROM

The Web (ISAPI) filter sample WebResponseModifier is provided on the ISA Server CD-ROM in the sdk\samples\Web_filters folder. The filter collects response chunks and allows you to change them depending on the complete response.

For more details about the WebResponseModifier sample, see Webresponsemodifier.

This section, Using Internet Security and Acceleration, contains the following topics:

  • Extending ISA Storage
  • Adding a Custom Event and Alert
  • ISA Administration Scripting
  • Extending ISA Management
  • Developing Application Filters
  • Developing Web (ISAPI) Filters for ISA
  • Managing the ISA Server Cache


Extending ISA Storage

This section describes how to add extensions to Internet Security and Acceleration (ISA) Server 2000 by using the FPCVendorParametersSets collection.

The vendor component must use the ISA central configuration management facilities to store its configuration. The facilities hide the storage location (local or Microsoft® Active Directory™), and provide support for promotion to Active Directory, central backup-and-restore capabilities, and sharing with all array members. A vendor can create new objects or associate additional information to system-defined objects by means of the FPCVendorParametersSets collection.

For example, an application filter can be added to ISA Server by using the FPCVendorParametersSets collection. This filter will then save the Multipurpose Internet Mail Extensions (MIME) data types that it needs to filter; this data will be stored by means of the collection's Save method and will be associated with that filter. After this extension is made to ISA Server, the vendor-specific data will be backed up with all other ISA data.

ISA storage is hierarchical. An extension developer can pick any node to extend. For example, you may want the extension to be per array, and therefore stored under the array node, or per computer, and therefore stored under the computer node.

See Also

FPCVendorParametersSet


Adding a Custom Event and Alert

The alert service of Internet Security and Acceleration (ISA) can be configured to signal an alert when an event occurs that an administrator should be aware of, such as an intrusion detection. The way ISA handles this and other events can be customized through the administration COM objects.

This section contains the following topics:

  • How to Add an Event and Alert
  • Using Environment Variables in Alerts


How to Add an Event and Alert

This topic describes the entire process of adding a custom event and alert to ISA Server. This is a step-by-step process, with examples in Visual Basic® Scripting Edition (VBScript) code.

ISA Server includes predefined events that administrators can use in creating alerts, that is, actions that will take place when an event occurs. Typically, a new event will be defined and added to ISA by a third-party vendor, who anticipates a need for an event related to an ISA Server add-on. Once the event is available in ISA Server, an administrator can define an alert.

For this example, the added event will signify attacks related to the Domain Name System (DNS). There are four types of events: DNS Host Name Overflow, DNS Length Overflow, DNS Zone High Port, and DNS Zone Transfer.

Use the following steps to add a custom event and alert to ISA:

  1. Add a new event definition by using the FPCEventDefinitions collection, as described in Adding a Custom Event.
  2. Define a new alert for this event through ISA Management, as described in Adding a Custom Alert.
  3. Signal the new event, as described in Signal the Event.

Note ISA administration objects can be used with any language that supports COM. You need not use Visual Basic® Scripting Edition (VBScript) to add a custom event or alert. An example of using C++ to create a custom event and alert is provided in the topic Raising an Event When a String is Found.


Adding a Custom Event

ISA events describe conditions that require the attention of an administrator, such as a disk-full event. Because an event may occur frequently, you may want to configure the related alert to be activated only if an event occurs a certain number of times. For more information, see the documentation for the FPCAlertNotification.SignalEvent and FPCAlertNotification.Signal_N_Events methods.

Following is an example of adding a new event definition to the FPCEventDefinitions collection using VBScript code. In this example, the additional-keys table is used. Additional keys serve as a way to subdivide event objects into related subevents; for example, subdividing a disk-full event into log-disk-full or system-disk-full subevents. This allows you to define several alerts that are specific to subevents or one alert that is specific to all subevents.

Note The additional key with an index = 0 means all subevents.

Example

Sub AddEvent()
Set eventdefs = CreateObject("FPC.Root").Arrays.GetContainingArray.PolicyElements.EventDefinitions
eventdefs.Refresh            ' Update object
    EventGUID = "{DF2D1202-929C-11d2-872C-00A02453BDDE}"

    ' Define a new custom event

    ' Fill in table of additional keys
    Dim AdditionalKeys(4)
    AdditionalKeys(0) = "All DNS attacks"
    AdditionalKeys(1) = "DNS Host Name overflow"
    AdditionalKeys(2) = "DNS Length Overflow"
    AdditionalKeys(3) = "DNS Zone High Port"
    AdditionalKeys(4) = "DNS Zone Transfer"

    Set MyEvent = eventdefs.Add("DNS Attack", EventGUID, AdditionalKeys)

    MyEvent.Save            ' Save changes
End Sub

See Also

FPCEventDefinition


Adding a Custom Alert

The FPCAlert object defines an alert. When a specific event occurs, this object determines the actions that ISA takes in response to that event. The FPCAlert object also defines the three thresholds that determine when actions will be taken. Alerts allow ISA to notify an administrator when certain events take place. The administrator can decide in advance which actions to take. You can access the properties of the actions to be taken through the FPCAlertActions collection.

This topic explains how to add a new alert to ISA. To a filter developer, adding a new alert is not necessary, but it could be useful for testing.

The most efficient way to add a new alert to ISA is from ISA Management. To add an alert, open ISA Management. Right-click the Alerts node in the console tree. On the menu, select New and Alert. Follow the instructions in the wizard.

See Also

FPCAlertAction


Signal the Event

This topic shows the signaling of the event. The variable 'AdditionalKey' is the index into the additional-keys table, and holds the value of 2, signifying that this event is "DNS Length Overflow". The following code assumes that the "DNS Length Overflow" event occurred.

Note SignalEvent will usually be called from C++ code. VBScript, as in the example below, is likely to be used for testing purposes.

Example

Sub SignalEvent()
    Set AlertNotification = CreateObject("FPC.AlertNotification.1")

    Dim SysLogEventStrings(1)

    EventGUID = "{DF2D1202-929C-11d2-872C-00A02453BDDE}"
    ServerName = Empty   'Meaning current machine
    AdditionalKey = 2    'Index in AdditionalKeys table specifying that "DNS Length Overflow" attack occurred.

    ' This parameter contains data needed for system log reporting
    SysLogEventType = 0
    SysLogEventCategory = 2
    SysLogEventSourceName = "ISS Filter"
    SysLogEventID = &H80000006
    'Assume that &h80000006 is ID of resource string such as: "DNS attack of type '%1' detected"
    SysLogEventStrings(0) = "DNS Length Overflow"  ' Will be substituted in the string above
   SysLogEventData = ContentOfPacket

   AlertNotification.SignalEvent EventGUID, ServerName, AdditionalKey, _
   "DNS attack detected", "ISS Filter detected a DNS attack", _
   SysLogEventID, SysLogEventSourceName, SysLogEventStrings, SysLogEventData, _
   SysLogEventCategory, SysLogEventType
End Sub ' SignalEvent

See Also

FPCAlertNotification


Using Environment Variables in Alerts

When an alert contains a program to execute, ISA provides environment variables with the event information to the executing process. The environment variables contain the inserted strings data from the event log. For each inserted string a corresponding ALERT_PARAMETER_X is added, where X is the sequence number of that string.

You can use the environment variables to refine a response to an event. For example, you can use the string representing an attacker's IP address to respond appropriately to the attack. An appropriate response could be the creation of a packet filter that blocks all packets from that IP address.

Environment Variable Example

The VBScript provided below creates a blocking packet filter for an IP address received in an attack event. It's based on the sample script StaticFilter.vbs.

In order to use the script as a response to an attack, you should create a new alert with the following parameters:

  1. Event - "Intrusion detected".
  2. Additional condition - a condition of interest to you, such as "Well-known port scan attack".
  3. Select Run a program as the action.
  4. Specify the following command line:
    %windir%\system32\cscript.exe StaticFilter.vbs

    where %windir% is your Windows 2000 installation directory, and StaticFilter.vbs is the full path to the script you want to run.

  5. For Use this account, leave the default Local system account.
'define the constants
const fpcBlockingPacketFilter = 2
const fpcCustomFilterType = 1
const fpcPfAnyProtocolIpIndex = 0
const fpcPfDirectionIndexBoth = 3
const fpcPfAnyPort = 1
const fpcPfAnyRemotePort = 1
const fpcPfDefaultProxyExternalIp = 1
const fpcPfSingleHost = 2

Private Sub SetStaticPacketFilter()
'Create the root object
Set ISA = CreateObject("FPC.Root")
ISA.Refresh

'Get the containing array
Set MyArray = ISA.Arrays.GetContainingArray

' Create blocked filter to all traffic from the attacker IP
Set pf = MyArray.ArrayPolicy.IpPacketFilters.Add("Block attacker",fpcBlockingPacketFilter)
pf.Description = "Block all traffic from attacker"

' set the filter parameters
pf.Enabled = True
pf.AllServers = True
pf.FilterType = fpcCustomFilterType
pf.ProtocolNumber = fpcPfAnyProtocolIpIndex

' allow bidirectional traffic so packets can be sent and received
pf.PacketDirection = fpcPfDirectionIndexBoth

' define the local host type
pf.SetLocalHost fpcPfDefaultProxyExternalIp

' set the local port type
pf.LocalPortType = fpcPfAnyPort

' set the protocol port type & number
pf.RemotePortType = fpcPfAnyRemotePort

' limited to only work with a specific attacker machine on the Internet

Set WshShell = WScript.CreateObject("WScript.Shell")
Set WshEnv = WshShell.Environment("Process")
'the environment variable 'ALERT_PARAMETER_1' contains the attacker IP
pf.SetRemoteHost fpcPfSingleHost, WshEnv("ALERT_PARAMETER_1")

MyArray.Save
End Sub

SetStaticPacketFilter


ISA Administration Scripting

The ISA Server administration object model gives developers a mechanism to extend ISA functionality. Scripting allows you to use the ISA administration COM objects to access and control any ISA array within an organization. The administration objects allow for automation of everything done using ISA Management. This capability allows administrators to create scripts to automate repetitive tasks requiring the use of ISA Management; these scripts can then be included in batch files. By programming with the same administration objects that ISA itself uses, developers can provide persistent, and configurable, data storage for their programs, and can have the ISA Server notify programs when the configuration data has changed.

Using the Microsoft® Management Console (MMC), developers can also customize ISA Management by adding new property pages, menus, toolbars, and buttons, and by extending the name space. See Extending ISA Management for examples of ISA Management customization.

The following topics demonstrate how all administrative tasks carried out with ISA Management can be automated through the use of the administration objects.

  • Getting Started with Administration Objects
  • Constructing the Local Address Table
  • Adding a Packet Filter
  • Configuring Arrays
  • Configuring Schedules
  • Configuring Destination Sets
  • Restricting Site Access
  • Adding Internet Access for New Users
  • Backup and Restore
  • Enterprise and Array Policy
  • Scenarios
  • Script Samples


Getting Started with Administration Objects

To start using administration COM objects, set up your development environment using either of the following procedures, depending on whether you use Microsoft Visual Basic® or C++. You must have ISA installed for the procedures to work.

To start using administration objects with Visual Basic

  1. Start Microsoft Visual Basic and open a new Standard EXE project.
  2. On the Project menu, click References.
  3. Select Microsoft Internet Security and Acceleration Server 2000 Administration Library from the dialog box that appears. This library is defined in msfpccom.dll, which is a file included with ISA. Therefore, you need to have ISA installed for access to this library. This will make all the administration COM objects available to you.
  4. Create the root ISA object as described in Creating the Root ISA Object.
  5. Write your program. See Add a Schedule for an introductory example.
  6. To apply your changes, you must call the Save method as described in Saving and Refreshing Objects.

If you are using Visual Basic Scripting Edition (VBScript), and would like to use enumerated types, see Using Enumerated Types in Scripts.

Note Unless otherwise noted, the examples in this section are written in Visual Basic, but you can use any language to script with the administration objects. If, for example, you script with VBScript, you can use any text editor to create the scripts.

To start using administration objects with C++

Include the file msfpccom.dll by using the following line of code:

#import "msfpccom.dll"

The file msfpccom.idl contains the definitions of the ISA administration objects.

For an example of an administration task performed using C++ code, see Adding a Schedule Using C++.

This section contains the following topics:

  • Creating the Root ISA Object
  • Saving and Refreshing Objects
  • Restarting Services after Configuration Changes
  • Using Enumerated Types in Scripts
  • Managing Dependent Objects
  • Managing Collections
  • ISA Management for Standard Edition and Stand-Alone Servers
  • ISA Management from Active Server Pages


Creating the Root ISA Object

You can access all ISA administration COM objects through a single root object. You must first create this root object and then use its properties to access subordinate objects in the object model. All server arrays and other configurational settings are accessed through the root object.

To create this root object in a scripting language such as VBScript or Microsoft JScript®, use the CreateObject function. Use the class name "FPC.Root", as in these examples:

  • VBScript
    Set objFPC  = CreateObject ("FPC.Root")
  • JScript
    objFPCRoot = new ActiveXObject  ("FPC.Root");

When creating the root object in Visual Basic, use the following:

Dim objFPC As New FPCLib.FPC

CreateObject is also available to Visual Basic programmers and so, alternatively, the following can be used:

Dim objFPC As New FPCLib.FPC
Set objFPC = CreateObject("FPC.Root")

Creation of the root object is the first step in all ISA scripts. If you are using Visual Basic, you must have the Microsoft Internet Security and Acceleration Server 2000 Administration Library selected as a project reference to create this object. Select the library in the Project References menu of the Visual Basic editor.

Note A script that will be run from a remote administration computer must use the FPCDS object, as follows:

  • VBScript
    Set objFPC  = CreateObject ("FPCDS.Root")
  • JScript
    objFPCRoot = new ActiveXObject ("FPCDS.Root");

When creating the root object in Visual Basic, use the following:

Dim objFPC As New FPCLib.FPCDS

OR

Dim objFPC As New FPCLib.FPC
Set objFPC = CreateObject("FPCDS.Root")

For more information on the FPCDS object, see FPC.


Saving and Refreshing Objects

Many ISA administration COM objects have methods you can use to save their settings to persistent storage or to refresh their settings from values in persistent storage.

Saving Objects

The Save method stores all settings of an object in persistent storage. It is important to note that you can save no changes unless you call the Save method. For example, if you change the value of a property, you must explicitly save the changes to the object, or the change will not be written to persistent storage.

In the following example, the change made to the name of the schedule will not be saved until the Save method is called on the last line of code.

Dim objFPC As New FPCLib.FPC
' declare schedule collection
Dim MySchedules As FPCSchedules
' declare schedule object
Dim MySchedule As FPCSchedule
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.GetContainingArray.PolicyElements.Schedules
' find "Extended Work Hours"
Set MySchedule = MySchedules("Extended Work Hours")
' rename the schedule
MySchedule.Name = "Unusual Work Hours"
' save changes
MySchedule.Save

Note Some objects do not have a Save method. To save these objects, invoke the Save method of a parent of the object in the hierarchy. An example of this is the FPCCacheDrives.Save method.

Refreshing Objects

If you need to abandon changes you've made to an object — while preserving the object in memory — use the Refresh method. The Refresh method reads the last saved values from persistent storage and applies them to the object and its subordinate objects.

The Refresh method retrieves and applies the last saved settings for an object and any subordinate objects. Use the Refresh method to be sure you have the current values for an object and its subordinate objects.

The Refresh method overwrites any changes made but not saved when it applies values from persistent storage. This can be useful when you want to cancel changes that have been made but not yet saved with the Save method.

In the following example the name of the schedule never changes because the Save method is not called before the Refresh method is called.

Dim objFPC As New FPCLib.FPC
' declare schedule collection
Dim MySchedules As FPCSchedules
' declare schedule object
Dim MySchedule As FPCSchedule
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.GetContainingArray.PolicyElements.Schedules
' find "Extended Work Hours"
Set MySchedule = MySchedules("Extended Work Hours")
' rename the schedule
MySchedule.Name = "Unusual Work Hours"
'Refresh, do not save changes
MySchedule.Refresh


Restarting Services after Configuration Changes

Many configurations changes that you make require the restarting of the Firewall service and/or the W3proxy (Web proxy) service. If you make a change by using a script, your script can use the FPCArray.SendRestartNotification method to stop and start the relevant service. Otherwise, the service can be stopped and started through ISA Management, as described in the ISA Server documentation.

The following table summarizes the requirements.

Action | Service to be restarted
Adding, removing, enabling or disabling an application filter | Firewall service
Reducing or increasing cache size | W3proxy service
Adding or removing a disk from the cache | W3proxy service
Changing the LAT so that the Network Interface Card (NIC) internal/external state changes | Firewall and W3proxy services
Enabling and disabling of packet filtering | Firewall and W3proxy services
Enabling or disabling a NIC | Firewall and W3proxy services
Changing the IP address of a NIC | Firewall and W3proxy services
Making changes to the routing table | Firewall service
Changing Web filter configuration | W3proxy service
Changing the port numbers on which the W3proxy service listens | W3proxy service
Updating SSL certificates | W3proxyservice


Using Enumerated Types in Scripts

Unlike Visual Basic or Microsoft Visual C++®, scripting languages, such as Visual Basic Scripting Edition (VBScript) or JScript®, do not support the use of enumerated values.

For this reason the ISA SDK includes two files that define as constants the enumerated values used in ISA.

The file fpccfg.vbs defines enumerated values in VBScript format.

The file fpccfg.js defines enumerated values in JScript format.

To use enumerated types when composing VBScript or JScript script files, copy the relevant constant definitions from the relevant fpccfg file to the constant declarations in your code.

For example, include the following code in the declarations section of your script:

const fpcRuleActionDeny = 1
const fpcAppliesToAll = 0
const fpcAppliesToAllContent = 0
const fpcSpecifiedDestinationSet = 3
const fpcArrayScope = 0

The declaration of constants allows you to write the following:

Set rules = array1.ArrayPolicy.SiteAndContentRules
Set rule = rules.Add("myrule")
rule.Action = fpcRuleActionDeny
rule.AppliesToMethod = fpcAppliesToAll
rule.AppliesToContentMethod = fpcAppliesToAllContent
rule.SetAppliesAlways
rule.SetDestination fpcSpecifiedDestinationSet, "Emergency", fpcArrayScope

If you always declare the appropriate constants in your declarations section at the beginning of each script, you can use enumerated types as you use them in C++ programs.

Alternatively, you can achieve the same effect by hard coding the values, as shown in the following code:

Set rules = array1.ArrayPolicy.SiteAndContentRules
Set rule = rules.Add("myrule")
rule.Action = 1
rule.AppliesToMethod = 0
rule.AppliesToContentMethod = 0
rule.SetAppliesAlways
rule.SetDestination 3, "Emergency", 0

These lines will perform the same task as the previous code lines, without the use of enumerated types.

When composing Windows Script (WS) or Windows Script File (WSF), which are Windows Script Host files, or when embedding scripts in HTML files, the constants files can be included by using the following statement (JScript example shown):

<script language="JScript" src="fpccfg.JS">

For more information about Windows Script Host, see the MSDN library.


Managing Dependent Objects

Many ISA objects depend upon other objects. This means that you access dependent objects through the properties of their parent object. Keep the following considerations in mind as you manage these dependent objects in your code:

  • When adding an object that contains a reference to another object or when modifying the name of the referenced object, ISA attempts to verify the existence of the referenced object. If the referenced object cannot be verified, the operation fails.
  • For example, the following code
    MySiteAndContentRule.SetDestination fpcSpecifiedDestinationSet, "Sports Destinations", fpcArrayScope

    adds a new destination set to a site and content rule. This code fails if the FPCDestinationSet collection named "Sports Destinations" has not been previously created. See Restricting Site Access for a fuller example of adding a destination set to a site and content rule.

  • When removing an object that is referenced by another object, ISA checks all instantiated objects to learn whether there are other references to the deleted object. If such references exist, the operation fails.

For example, if the FPCDestinationSet object named "Sports Destinations" is referenced by more than one FPCSiteAndContentRule object, code that removes the destination set will fail. If no other object references the destination set, "Sports Destinations" will be removed successfully.


Managing Collections

A collection is an object that holds many individual objects of the same type. Usually, the name of the collection will be the plural of the name of the individual object types within the collection; for example, the FPCListenEntries collection holds FPCListenEntry objects.

Collections allow you to quickly assign settings to multiple objects of the same type with a script. For example, a collection is used to hold the entries in the ISA Local Address Table (LAT), in the form of FPCLATEntry objects. You can easily populate or export the LAT table with a simple script. See Collection Methods and Properties, for specific method and property information.

ISA administration object collections do not support nested For Each loops on the same collection object. For example, the following nested loops will not work because both loops operate on the same collection object:

For Each Rule1 in Array.ArrayPolicy.SiteAndContentRules
    For Each Rule2 in Array.ArrayPolicy.SiteAndContentRules
        MsgBox Rule1.Name & Rule2.Name
    Next
Next

The following pair of nested For Each loops will work because each loop applies to a different collection object:

For Each Array in Arrays
    For Each Rule in Array.ArrayPolicy.SiteAndContentRules
        MsgBox Rule.Name
    Next
Next


Collection Methods and Properties

All objects that are a part of a collection have a similar set of methods and properties, which are all or a combination of the following.

Method | Description
Save | Saves all the objects within the collection to persistent storage. Modifications made to the collection will not be saved until after this method is called. The Save method is recursive, so calling the Save method of the collection will save every object within the collection.
Refresh | Reads the latest saved configuration settings from persistent storage and applies them to the object collection. The Refresh method does not check whether there are any unsaved changes made to the objects, so all changes made after the last Save method call will be lost. The Refresh method is useful when you want to cancel changes that have been made but not yet saved with the Save method.
Add | Adds an object to the collection, and returns a reference to the newly created object. This method takes a string parameter that identifies the new object. The string parameter can be used later to retrieve the object by using the Item method. To save this new object to persistent storage, call the Save method.
Remove | Removes an object from the collection. This method takes a string parameter or index of the object to be removed from the collection.
Item | Returns the given object from the collection. This method retrieves an object by an index that is an integer value. It may also retrieve the object by using the name of the object, which is a string value.

Property | Description
Count | Returns an integer value of the number of objects in the collection.
VendorParametersSets | Retrieves a reference to an object for storing and loading of custom data into the collection's storage. The VendorParametersSets property is designed to integrate third-party extensions into ISA Server.

While most collections of objects work in the same way, see individual collection reference pages for particular descriptions.

Note With Visual C++, you can browse a collection to find a particular item by using the _NewEnum property or the Item method. ISA collections include the _NewEnum property and the Item method. The Item method is described in the ISA Server SDK reference. For more information about _NewEnum, see the ISA Server SDK msfpccom.idl file.

In Visual Basic, you do not need to use the _NewEnum property, because it is automatically used in the implementation of For Each ... Next.


ISA Management for Standard Edition and Stand-Alone Servers

Certain methods, properties, parameters and parameter values are available only for ISA Server Enterprise Edition arrays. They are not available for ISA Server Standard Edition, or for stand-alone servers in the Enterprise Edition.

Methods

  • FPCArrays.Add
  • fpcFetchNoArrayRouting flag in FPCCacheContents.FetchURL
  • FPCServers.Remove
  • pIsArrayPolicyAllowed and pIsEnterprisePolicyUsed values in IFWXFilterAdmin::GetConfigurationType
  • FpcItemScope parameter in FPCServerPublishingRule.SetProtocol
  • ItemScope parameter in FPCSiteandContentRule.SetDestination
  • Scope parameter in IFWXFilterAdmin::UnregisterProtocolForFilter
  • Scope parameter in IFWXFilterAdmin::GetProtocol
  • Scope parameter in IFWXFilterAdmin::GetParameterSets
  • Scope parameter in IFWXFilterAdmin::GetFilterParameterSet

Properties

  • FPCWebProxy.CARPNameSystem
  • FPCWebRequestConfiguration.ResolveInArray
  • fpcBackupEnterpriseConfiguration value in FpcBackupType
  • FPCWebProxy.LoadSize
  • FPCIpPacketFilter.AllServers


ISA Management from Active Server Pages

It is possible to access ISA Server administration objects from active server pages (ASPs). However, an ASP that uses ISA Server administration objects may not work under the default IIS setting that allows anonymous access, resulting in an access denied error. This is because when anonymous access is enabled, your ASP page will not have access to ISA storage, and there is also a possibility that permission issues will arise.

In order for the ASP to successfully use the ISA administration objects, you must disable anonymous access in IIS. Users with permissions will then be allowed to run the ASP page. Users without permissions will continue to get an access denied error, as they would have under anonymous access.

For information on how to disable anonymous access in IIS , see MSDN.


Constructing the Local Address Table

The Local Address Table (LAT) consists of a series of IP address ranges that define your internal network address space. Typically, the LAT contains all IP addresses associated with the internal network cards on the ISA Server computer, in addition to the private IP address ranges defined by the Internet Assigned Numbers Authority (IANA). For more information see the ISA product documentation.

You can use the ISA administration COM objects to build the LAT. The folder SDK\samples\admin\scripts includes the ConstructLAT script that constructs a LAT. It is provided in both VBScript and JScript.

Adding a LAT Entry

The following VBScript code demonstrates how to add an entry to the LAT:

Set objFPC  = CreateObject ("FPC.Root")
Set objNetConfig = objFPC.Arrays(1).NetworkConfiguration
Set objLAT = objNetConfig.LAT
ObjLAT.Add "2.2.2.2","3.3.3.3"
ObjLAT.Save


Adding a Packet Filter

ISA Server's packet-filtering features allow you to control the flow of information to and from ISA Server. With packet filtering, you can intercept and either allow or block packets destined for specific computers on your corporate network.

You can use administration COM objects to add and configure packet filters. This is done by using the FPCIpPacketFilter object.

The following example adds a packet filter that applies to all the servers within the array arr:

' this code creates a static filter for a service that is running
' on the ISA server and needs to connect to
' NTP server on the Internet at a known address.

Dim objFPC As New FPCLib.FPC
Dim arr As FPCArray
Dim pf As FPCIpPacketFilter
Set arr = objFPC.Arrays.GetContainingArray
Set pf = arr.ArrayPolicy.IpPacketFilters.Add("NetTime", fpcAllowingPacketFilter)
pf.Description = "NTP filter for My App"

' apply to all servers in the array
pf.AllServers = True
pf.FilterType = fpcCustomFilterType
pf.ProtocolNumber = 17

' allow both send and receive
pf.PacketDirection = fpcPfDirectionIndexBoth
' application runs on the ISA Server computer
pf.SetLocalHost fpcPfDefaultProxyExternalIp
pf.LocalPortType = fpcPfDynamicPort

' connecting to a well-known server on the Internet
pf.RemotePortType = fpcPfFixedRemotePort
pf.RemotePortNumber = 123
pf.SetRemoteHost fpcPfExternalIpRange, "123.21.32.11", "255.255.255.255"
pf.LogMatchingPackets = False
' enable the filter
pf.Enabled = True
' save the changes
arr.Save

See Also

FPCIpPacketFilters


Configuring Arrays

Setting up a network can involve configuring many servers. With ISA, you can configure multiple servers at the same time through the array-level properties and methods of the FPCArray object, which is a member of the FPCArrays collection. ISA arrays are set up programmatically through individual FPCArray objects.

Each ISA array is a set of servers that have a similar configuration and share various resources to increase efficiency. For example, servers in an array share cached Web pages, so that a client attached to one of the computers benefits from pages cached on all of them.

The FPCArrays collection is a property of the ISA root object.

You can obtain a reference to a FPCArray object by using either of two methods of the FPCArrays collection:

  • Item method
  • GetContainingArray method

The Item method of the FPCArrays collection returns a reference to any array you identify by index or name. Here is a VBScript example:

Set objMyArray = objFPCRoot.Arrays(1)

The GetContainingArray method of the FPCArrays collection returns a reference to the current array. The current array is the server array containing the server that executes this code. You can quickly obtain a reference to the current array by using code similar to this:

Set objCurArray = objFPCRoot.Arrays.GetContainingArray

Alternatively, you can use a more sophisticated scripting approach to allow real-time selection of an array while the script is running. The following code automatically inserts the name of the current array in the input box. The user can also type the name of a different array. If the input box is left empty, it is the equivalent of clicking Cancel.

Set objArrays = ISA.Arrays

        strArrayName = InputBox("Please enter the array name, or <ENTER> for the Containing Array:",,ISA.Arrays.GetContainingArray.Name)

        If strArrayName = "" Then
    'Cancel option
    Exit Sub
        Else
    On Error Resume Next
    Set Settings = objArrays(strArrayName).ClientConfig.Firewall.Settings
    If Err.Number <> 0 Then
        Wscript.Echo "The specified array was not found"
        Exit Sub
    End If
    On Error GoTo 0
        End If

The FPCArray object has properties that provide access to other parts of the administration object model, a factor that can be useful when setting up a network. For details see FPCArray in the ISA SDK reference.

See Also

ISA Array Examples


ISA Array Examples

The following code uses the FPCArray.Servers property to return the name of an individual server.

Dim objFPC As New FPCLib.FPC
Dim serverName As String
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays(1)
serverName = objFPCArray.Servers(1).Name
MsgBox serverName

The following code retrieves the name of the containing array by using the GetContainingArray method.

Dim objFPC As New FPCLib.FPC
Dim CurrentArray As String
Dim objFPCArrays As FPCArrays
Set objFPCArrays = objFPC.Arrays
CurrentArray = objFPCArrays.GetContainingArray.Name
MsgBox CurrentArray


Configuring Schedules

You can use the ISA administration COM objects to add, modify, or delete a schedule. Each ISA schedule is represented by an FPCSchedule object within the FPCSchedules collection.

This section contains the following topics:

  • Add a Schedule
  • Modify a Schedule


Add a Schedule

The schedules collection is accessed through the Schedules property of the FPCPolicyElements object, as shown in the examples in this topic:

  • Adding a Schedule Using Visual Basic
  • Adding a Schedule Using C++


Adding a Schedule Using Visual Basic

The following is a portion of Visual Basic code that adds a new schedule called "Extended Work Hours", which includes all hours on all days:

Dim objFPC As New FPCLib.FPC
' declare schedule collection
Dim MySchedules As FPCSchedules
' declare schedule object
Dim objNewSchedule As FPCSchedule
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.GetContainingArray.PolicyElements.Schedules
' Add new Schedule
Set objNewSchedule = MySchedules.Add("Extended Work Hours")
' Set the Schedule days
objNewSchedule.Set fpcALL_WEEK, fpcALL_DAY
' save your changes
MySchedules.Save

Note that the changed schedule is not saved to persistent storage until the last line of code, where the Save method is called.

See Also

FPCSchedule, Modify a Schedule


Adding a Schedule Using C++

The following is a portion of C++ code that adds a new schedule called "Extended Work Hours", which includes all hours on all days. This code was written as a Windows Console Application. To use this code:

  1. In Visual C++, create a new Win32 Console Application.
  2. Select the default empty project.
  3. Create a new C++ source file in the workspace.
  4. Paste the following code into the C++ source file, and build the project.
    //Import the ISA msfpccom.dll file so that ISA COM objects can be used.
//Use the path to your ISA installation directory, or search for msfpccom.idl

#import "d:\Program Files\Microsoft ISA Server\msfpccom.dll"

int main ()
{
// Define variables.
HRESULT hr;

//Initialize the COM library on the current thread.
hr = CoInitialize( NULL );

{
// Define variables.
FPCLib::IFPCPtr sipFPCRoot;
FPCLib::IFPCSchedulesPtr sipMyScheduleCol;
FPCLib::IFPCSchedulePtr sipMySchedule;

// Create the ISA root object.
hr = sipFPCRoot.CreateInstance("FPC.Root");
//Get the schedules collection.
sipMyScheduleCol = sipFPCRoot->Arrays->GetContainingArray()->PolicyElements->Schedules;
//Add the schedule.
sipMySchedule = sipMyScheduleCol->Add("My New Schedule");
//Set the schedule
sipMySchedule->Set(FPCLib::fpcALL_WEEK, FPCLib::fpcALL_DAY);
//Save your changes.
sipMyScheduleCol->Save();
}

CoUninitialize();

return 0;
}
  5. Run the application.

See Also

FPCSchedule, Modify a Schedule


Modify a Schedule

The following portion of Visual Basic code modifies the schedule example shown in Add a Schedule by using the UnSet method of the FPCSchedule object. The schedule "Extended Work Hours" is changed so that it includes all hours of the day, but only the days Monday through Friday. This is done by unsetting the days Saturday and Sunday:

Dim objFPC As New FPCLib.FPC
' declare schedule collection
Dim MySchedules As FPCSchedules
' declare schedule object
Dim MySchedule As FPCSchedule
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.GetContainingArray.PolicyElements.Schedules
' find "Extended Work Hours"
Set MySchedule = MySchedules("Extended Work Hours")
' remove Saturday and Sunday from the schedule
MySchedule.Unset fpcSAT, fpcALL_DAY
MySchedule.Unset fpcSUN, fpcALL_DAY
' save changes
MySchedules.Save

Again, note that the changes will not be saved to persistent storage until the last line of code, where the Save method is called.

The topic, Configuring Destination Sets, shows the addition of a new set of forbidden destinations to the FPC destination sets collection. The next section, Restricting Site Access, shows how to restrict site access through a new site and content rule. The new site and content rule applies to both the schedule created in this example, and the forbidden sites added in the Configuring Destination Sets topic.

See Also

FPCSchedule, Add a Schedule


Configuring Destination Sets

A destination set is a group of one or more computer or folders on specific computers, grouped together for the purpose of applying rules and policies. Single destinations are grouped in a FPCDestinationSet collection that can be used to define of site and content rules, publishing rules, bandwidth rules, or routing rules. For example, you can create a destination set that contains restricted sport sites, and then define a site and content rule that prohibits access to these destinations during work hours.

The FPCDestinationSets collection is accessed through the DestinationSets property of the FPCPolicyElements object, as shown here:

Dim objFPC As New FPCLib.FPC
Dim MyDestinationSets As FPCDestinationSets
Set MyDestinationSets = objFPC.Arrays.GetContainingArray.PolicyElements.DestinationSets

A destination consists of two parts — a host description and a path within this host. For example, in the destination "www.microsoft.com/scripting", "www.microsoft.com" is the host and "/scripting" is the path. If the path is empty, the destination set defines the entire domain. A path within the host is only relevant when using the HTTP protocol. A host can be specified by a domain name, an IP address, or an IP range denoted by a From and To pair of settings.

You can add, delete, and modify destination sets by using COM objects.

  • Add a Destination Set
  • Modify a Destination Set


Add a Destination Set

The following portion of Visual Basic code adds a new destination set called "Sports Sites", including the site "www.sports.microsoft.com", to the destination sets collection:

Dim objFPC As New FPCLib.FPC
' declare the destination sets collection
Dim MyFPCDestinationSets As FPCDestinationSets
' declare the destination set collection
Dim MyFPCDestinationSet As FPCDestinationSet
' declare the destination object
Dim MyFPCDestination As FPCDestination
' set the destination sets to current array
Set MyFPCDestinationSets = objFPC.Arrays.GetContainingArray.PolicyElements.DestinationSets
' add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Sports Sites")
' add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("www.sports.microsoft.com")
' save your changes
MyFPCDestinationSets.Save

Note that the additional destination set will not be saved to persistent storage until the last line of code, where the Save method is called.

See Also

FPCDestinationSet, Modify a Destination Set


Modify a Destination Set

ISA administration COM objects also permit programmatic modification of existing destination sets. The following portion of Visual Basic code modifies the destination set from the previous topic, adding the sites "www.mysports.microsoft.com", "www.mysport.microsoft.com", and "www.sport.microsoft.com" to the destination set "Sports Sites":

Dim objFPC As New FPCLib.FPC
' declare the destination sets collection
Dim MyFPCDestinationSets As FPCDestinationSets
' declare the destination set collection
Dim MyFPCDestinationSet As FPCDestinationSet
' declare the destination object
Dim MyFPCDestination As FPCDestination
' set the destination sets to current array
Set MyFPCDestinationSets = objFPC.Arrays.GetContainingArray.PolicyElements.DestinationSets
' find set "Sports Destinations"
Set MyFPCDestinationSet = MyFPCDestinationSets.Item("Sports Sites")
  'make adjustments to destination here
  Set MyFPCDestination = MyFPCDestinationSet.Add("www.mysports.microsoft.com")
  Set MyFPCDestination = MyFPCDestinationSet.Add("www.mysport.microsoft.com")
  Set MyFPCDestination = MyFPCDestinationSet.Add("www.sport.microsoft.com")
'save changes
MyFPCDestinationSets.Save

The preceding code can be used in the context of a program or script that runs every day and adds new forbidden destinations to existing forbidden destination sets. If, for example, an administrator receives a daily list of forbidden sites from an outside service, this use of the objects automates the task of importing the new forbidden destinations.

The topic, Restricting Site Access, shows how to restrict site access by using a new site and content rule. The rule applies both to the forbidden sites added in the preceding example, and to the schedule added in the topic Add a Schedule.

See Also

FPCDestinationSet, Add a Destination Set


Restricting Site Access

Site access is restricted through the use of a site and content rule. Each site and content rule is represented by a FPCSiteAndContentRule object and accessed through the FPCSiteAndContentRules collection. A site and content rule defines actions that ISA Server will take when specific users attempt to access specific sites or content through ISA.

  • Add a Site and Content Rule
  • Modify a Site and Content Rule


Add a Site and Content Rule

The followingportion of Visual Basic code adds a new site and content rule called "Workday Site Restriction". It refers to the "Extended Work Hours" schedule, which you can see in Add a Schedule. The example here also refers to the destination set "Sports Sites" that appeared in the example in Add a Destination Set.

Dim objFPC As New FPCLib.FPC
' declare collection
Dim MySiteAndContentRules As FPCSiteAndContentRules
' declare rule object
Dim objNewSiteAndContentRule As FPCSiteAndContentRule
' get the rule collection of the current array
Set MySiteAndContentRules = objFPC.Arrays.GetContainingArray.ArrayPolicy.SiteAndContentRules
' Add new rule object
Set objNewSiteAndContentRule = MySiteAndContentRules.Add("Workday Site Restriction")
objNewSiteAndContentRule.Description = "Deny sports sites"
objNewSiteAndContentRule.SetDestination fpcSpecifiedDestinationSet, "Sports Sites"
objNewSiteAndContentRule.SetSchedule "Extended Work Hours", fpcArrayScope
objNewSiteAndContentRule.Action = fpcRuleActionDeny
' save your changes
MySiteAndContentRules.Save

Note that the changes will not be saved to persistent storage until the last line of code, where the Save method is called.

See Also

FPCSiteAndContentRule Object, Modify a Site and Content Rule


Modify a Site and Content Rule

The following portion of Visual Basic code modifies the new rule explained in the previous topic, Add a Site and Content Rule. The modification changes the rule to redirect the user to a specific URL after denying the request, rather than merely denying the request. This URL could contain, for example, the company policy toward accessing sports sites during work hours.

Dim objFPC As New FPCLib.FPC
' declare rules collection
Dim MySiteAndContentRules As FPCSiteAndContentRules
' declare rule object
Dim MySiteAndContentRule As FPCSiteAndContentRule
' get the rule collection of the current array
Set MySiteAndContentRules = objFPC.Arrays.GetContainingArray.ArrayPolicy.SiteAndContentRules
' find rule
Set MySiteAndContentRule = MySiteAndContentRules("Workday Site Restriction")
  ' change rule values here
  MySiteAndContentRule.RedirectUrl "http://www.microsoft.sports.policy.com"
  MySiteAndContentRule.Action = fpcRuleActionRedirect
' save your changes
MySiteAndContentRules.Save

See Also

FPCSiteAndContentRule Object


Preventing Access to a Specific Site

There may be situations in which you may want to limit access to a specific destination. For example, downloads from a particular site may be known to present a security risk to your network. This section provides information on scripts that can limit access to a particular destination, or set of destinations. You can prepare a script similar to this one, and as soon as you know of a problematic destination, use the script to prevent access to the destination.

This section contains the following topics:

  • Preventing Site Access for an Array
  • Preventing Site Access for an Enterprise


Preventing Site Access for an Array

The following portion of Visual Basic code adds a new site and content rule, called "Emergency_Site_Restriction", on the array level. The rule serves only one function, to limit access to a particular site; for example, www.sitetoblock.tld.

Dim objFPC As New FPCLib.FPC
Dim array1 As FPCArray
Dim rules As FPCSiteAndContentRules
Dim rule As FPCSiteAndContentRule
Dim destinationset As fpcDestinationSet

'Set the variable array1 equal to the array on which the script is being run
Set array1 = objFPC.Arrays.GetContainingArray
'Get the destination sets collection
Set DestinationSets = array1.PolicyElements.DestinationSets
'Add a destination set called "Emergency"
Set destinationset = DestinationSets.Add("Emergency")
'Add a destination called "www.sitetoblock.tld"
Set destination = destinationset.Add("www.sitetoblock.tld")
'Save the destination set
destinationset.Save

'Get the Site and Content Rules collection
Set rules = array1.ArrayPolicy.SiteAndContentRules
'Add a rule called "Emergency_Site_Restriction"
Set rule = rules.Add("Emergency_Site_Restriction")
'Define the rule action to deny access
rule.Action = fpcRuleActionDeny
'Define that the rule applies to all users, which is the default
rule.AppliesToMethod = fpcAppliesToAll
'Define that the rule applies to all content, which is the default
rule.AppliesToContentMethod = fpcAppliesToAllContent
'Define that the rule always applies
rule.SetAppliesAlways
'Set the destination to which the rule applies
rule.SetDestination fpcSpecifiedDestinationSet, "Emergency", fpcArrayScope
'Save the rule
rule.Save

VBScript

The VBScript derived from the preceding Visual Basic code is shown here. Note the setting of the enumerated types as constants, as described in Using Enumerated Types in Scripts.

const fpcRuleActionDeny = 1
const fpcAppliesToAll = 0
const fpcAppliesToAllContent = 0
const fpcSpecifiedDestinationSet = 3
const fpcArrayScope = 0

set isa = WScript.CreateObject("FPC.Root")
Set array1 = isa.Arrays.GetContainingArray
Set DestinationSets = array1.PolicyElements.DestinationSets
Set destinationset = DestinationSets.Add("Emergency")
Set destination = destinationset.Add("www.sitetoblock.tld")
destinationset.Save

Set rules = array1.ArrayPolicy.SiteAndContentRules
Set rule = rules.Add("myrule")
rule.Action = fpcRuleActionDeny
rule.AppliesToMethod = fpcAppliesToAll
rule.AppliesToContentMethod = fpcAppliesToAllContent
rule.SetAppliesAlways
rule.SetDestination fpcSpecifiedDestinationSet, "Emergency", fpcArrayScope
rule.Save


Preventing Site Access for an Enterprise

The following portion of Visual Basic code adds a new site and content rule, called "Emergency_Site_Restriction", on the enterprise level. The rule serves only one function, to limit access to a particular site; for example, www.sitetoblock.tld.

Dim objFPC As New FPCLib.FPC
Dim rules As FPCSiteAndContentRules
Dim rule As FPCSiteAndContentRule
Dim destinationset As fpcDestinationSet

'Get the destination sets collection
Set DestinationSets = objFPC.Enterprise.PolicyElements.DestinationSets
'Add a destination set called "Emergency"
Set destinationset = DestinationSets.Add("Emergency")
'Add a destination called "www.sitetoblock.tld"
Set destination = destinationset.Add("www.sitetoblock.tld")
'Save the destination set
destinationset.Save

'Get the Site and Content Rules collection
Set rules = objFPC.Enterprise.EnterprisePolicies(1).SiteAndContentRules
'Add a rule called "Emergency_Site_Restriction"
Set rule = rules.Add("myrule")
'Define the rule action to deny access
rule.Action = fpcRuleActionDeny
'Define that the rule applies to all users, which is the default
rule.AppliesToMethod = fpcAppliesToAll
'Define that the rule applies to all users, which is the default
rule.AppliesToContentMethod = fpcAppliesToAllContent
'Define that the rule always applies
rule.SetAppliesAlways
'Set the destination to which the rule applies
rule.SetDestination fpcSpecifiedDestinationSet, "Emergency", fpcArrayScope
'Save the rule
rule.Save


Restricting Use of a Protocol

You may determine that there is a particular protocol that should not be used by your users. The Visual Basic code and VBScript provided here demonstrate how to create a protocol rule that prevents use of a particular protocol.

Visual Basic Code

The Visual Basic code for blocking use of a particular protocol is provided here.

Dim objFPC As New FPCLib.FPC
Dim array1 As FPCArray
Dim ProtocolRules As FPCProtocolRules
Dim ProtocolRule As FPCProtocolRule

Set array1 = objFPC.Arrays.GetContainingArray
'Get the protocol rules collection
Set ProtocolRules = array1.ArrayPolicy.ProtocolRules
'Add a rule called "Blocked"
Set ProtocolRule = ProtocolRules.Add("Blocked")
'The following six lines define the protocol rule
ProtocolRule.Action = fpcActionDeny
ProtocolRule.AppliesToMethod = fpcAppliesToAll
ProtocolRule.Description = "Emergency Protocol Blocking"
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
ProtocolRule.SpecifiedProtocols.Add "Gopher","",fpcEnterpriseScope
'Save the rule
ProtocolRule.Save

VBScript

The VBScript derived from the preceding Visual Basic code is shown here. Note the setting of the enumerated types as constants, as described in Using Enumerated Types in Scripts.

const fpcActionDeny = 1
const fpcAppliesToAll = 0
const fpcSpecifiedProtocols = 1
const fpcEnterpriseScope = 1

set objFPC = CreateObject ("FPC.Root")
Set array1 = objFPC.Arrays.GetContainingArray
Set ProtocolRules = array1.ArrayPolicy.ProtocolRules
Set ProtocolRule = ProtocolRules.Add ("Blocked")

ProtocolRule.Action = fpcActionDeny
ProtocolRule.AppliesToMethod = fpcAppliesToAll
ProtocolRule.Description = "Emergency Protocol Blocking"
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
ProtocolRule.SpecifiedProtocols.Add "Gopher","",fpcEnterpriseScope

ProtocolRule.Save


Preventing Access in a Web Publishing Scenario

In a Web publishing scenario, an out-of-band denial-of-service attack may be attempted against a computer protected by ISA Server. If mounted successfully, this attack causes the computer to crash or causes a loss of network connectivity on vulnerable computers.

ISA Server can be configured to detect an attack and generate an alert regarding the attempted intrusion. The source of the attack will appear in the event log. As a response, you can run a script that denies publishing-server access to the specific IP addresses where the attack originated. This is demonstrated in the Visual Basic code and VBScript provided here.

Visual Basic Code

The Visual Basic code for blocking access to a publishing server from a range of IP addresses is provided here.

Dim objFPC As New FPCLib.FPC
Dim array1 As FPCArray
Dim PublishingRules As FPCWebPublishingRules
Dim PublishingRule As FPCWebPublishingRule
Dim ClientSets As FPCClientAddressSets
Dim ClientSet As FPCClientAddressSet
Dim MyClientSets As FPCRefs

'Set the variable array1 equal to the array on which the script is being run
Set array1 = objFPC.Arrays.GetContainingArray
'Get the client address sets collection
Set ClientAddressSets = array1.PolicyElements.ClientAddressSets
'Add a client address set called "Attackers"
Set ClientAddressSet = ClientAddressSets.Add ("Attackers")
'Add a range of IP addresses to the client address set
Set ClientAddressSet = ClientAddressSet.Add("111.111.111.111", "111.111.111.115")
'Save the client address set
ClientAddressSets.Save

'Get the Web publishing rules collection
Set PublishingRules = array1.Publishing.WebPublishingRules
'Add a rule called "Stop Attackers"
Set PublishingRule = PublishingRules.Add("Stop Attackers")
'The next two lines make the rule use the intended client address set
'through the use of FPCRefs
Set MyClientSets = PublishingRule.ClientAddressSetsUsed
MyClientSets.Add "Attackers", "", fpcArrayScope
'The next five lines set the properties of the rule.
PublishingRule.SetWebSiteAndPorts fpcRouteDiscard, ""
PublishingRule.AppliesToMethod = fpcAppliesToClientSets
PublishingRule.SetDestination fpcAllInternalDestinations
PublishingRule.Description = "Stops attackers from accessing our site"
PublishingRule.Enabled = True
'Save the rule
PublishingRule.Save

VBScript

The VBScript derived from the preceding Visual Basic code is shown here. Note the setting of the enumerated types as constants, as described in Using Enumerated Types in Scripts.

Sub AccessBlock()
const fpcArrayScope = 0
const fpcRouteDiscard = 0
const fpcAppliesToClientSets = 2
const fpcAllInternalDestinations = 1

Set objFPC  = CreateObject ("FPC.Root")
Set array1 = objFPC.Arrays.GetContainingArray
Set ClientAddressSets = array1.PolicyElements.ClientAddressSets
Set ClientAddressSet = ClientAddressSets.Add("Attackers")
Set ClientAddressSet = ClientAddressSet.Add("111.111.111.111", "111.111.111.115")
ClientAddressSets.Save

Set PublishingRules = array1.Publishing.WebPublishingRules
Set PublishingRule = PublishingRules.Add("Stop Attackers")
Set MyClientSets = PublishingRule.ClientAddressSetsUsed
MyClientSets.Add "Attackers", "", fpcArrayScope
PublishingRule.SetWebSiteAndPorts fpcRouteDiscard, ""
PublishingRule.AppliesToMethod = fpcAppliesToClientSets
PublishingRule.SetDestination fpcAllInternalDestinations
PublishingRule.Description = "Stops attackers from accessing our site"
PublishingRule.Enabled = True
PublishingRule.Save
End Sub
AccessBlock


Adding Internet Access for New Users

You can add new users to ISA by means of the FPCAccounts collection. Each group of FPCAccount objects holds a set of accounts that can be associated with a site and content rule or a protocol rule. The FPCSiteAndContentRule object represents a site and content rule, and the FPCProtocolRule object represents a protocol rule. You use protocol rules and site and content rules to restrict Internet access for a group of ISA accounts.

The following code adds a new ISA account that represents a new user:

' add new user account
Dim objFPC As New FPCLib.FPC
Dim MyFPCAccounts As FPCAccounts
Dim MyNewFPCAccount As FPCAccount
Set MyFPCAccounts = objFPC.Arrays.GetContainingArray.ArrayPolicy.SiteAndContentRules(1).AppliesToAccounts
' add new user account to collection
Set MyNewFPCAccount = MyFPCAccounts.Add("REDMOND\USER", fpcInclude)

An ISA user's Internet access is governed by protocol rules, site and content rules, and schedules. To enable the user to have appropriate levels of Internet access, appropriate rules must apply to this ISA account.

The topic Applying Rules to User Accounts expands on the preceding code example by adding a new user and applying appropriate rules to the new user. This topic also expands on the topics Configuring Schedules, Configuring Destination Sets, and Restricting Site Access.


Applying Rules to User Accounts

A new user can be added to ISA through administration COM objects, as shown in the topic, Adding Internet Access for New Users. You can also apply rules to a new-user account by means of the objects. One way to control Internet access is with protocol rules. A protocol rule defines a set of protocols that are allowed to certain users at certain times. These times are defined by a schedule. Unlike site and content rules, protocol rules always define what is allowed rather than what is forbidden.

The following example adds a new user and applies the site and content rule "Workday Site Restriction" to the new ISA account.

Dim objFPC As New FPCLib.FPC
' get site and content rule
Dim MySiteAndContentRules As FPCSiteAndContentRules
Dim MySiteAndContentRule As FPCSiteAndContentRule
Set MySiteAndContentRules = objFPC.Arrays.GetContainingArray.ArrayPolicy.SiteAndContentRules
Set MySiteAndContentRule = MySiteAndContentRules.Item("Workday Site Restriction")
' add new user
Dim MyFPCFPCAccounts As FPCAccounts
Dim MyNewFPCAccount As FPCAccount
' AppliesToAccounts returns accounts collection for this rule
Set MyFPCAccounts = MySiteAndContentRule.AppliesToAccounts
MySiteAndContentRule.AppliesToMethod = fpcAppliesToUsers
' add new account to collection
Set MyNewFPCAccount = MyFPCAccounts.Add("REDMOND\USER", fpcInclude)
' added rule will apply to new user
' save your changes
MySiteAndContentRule.Save

The following code applies this site and content rule to the new account using the schedule "Extended Work Hours":

MySiteAndContentRule.SetSchedule "Extended Work Hours", fpcArrayScope
MySiteAndContentRule.Save  ' save your changes

See the topic Add a Schedule for an example of adding the schedule "Extended Work Hours".

See Also

FPCAccount, FPCSiteAndContentRule


Backup and Restore

An ISA administrator can back up all ISA settings of a specified array through ISA Management or through a program or script that uses the administration COM objects. The FPCArray.Backup method will back up all settings of an array, and the FPCArray.Restore method will restore all previously saved settings to an array. The Backup and Restore methods always cover all settings in a specific array.

  • Using the Backup Method
  • Using the Restore Method


Using the Backup Method

The Backup method backs up the current array data to a specific file. The Restore method can then be used to read the backed up data at a later time, and return the stored configurational settings to the array.

The following example backs up the current array to a file called "backup file".

Example

Dim objFPC As New FPCLib.FPC
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays.GetContainingArray
objFPCArray.Backup "backup file", "first backup"

See Also

Using the Restore Method


Using the Restore Method

The Restore method restores the settings stored in a file to the array, overwriting the array's previous settings.

The following example uses the Restore method to restore the current array settings from the file "backup file":

Example

Dim objFPC As New FPCLib.FPC
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays.GetContainingArray
objFPCArray.Restore "backup file"

See Also

Using the Backup Method


Enterprise and Array Policy

Administrators can define protocol rules and site and content rules; together, these rules constitute an enterprise-level policy. The enterprise policy can be applied to any array, and can be augmented by the array's own policy. The administrator can apply and configure a global policy using ISA Management or the ISA Server administration objects.

Note ISA Management includes a node called Access Policy, which includes Site and Content Rules, Protocol Rules, and IP Packet Filters. In the administration COM object model, this is represented by the FPCArrayPolicy object, which also includes the ISA Web proxy properties. This object does not include the publsihing rules of an array policy.

This section contains the following topics:

  • How Enterprise Policy Affects Array Policy
  • Add a New ISA Enterprise Policy


How Enterprise Policy Affects Array Policy

The enterprise administrator can select how the enterprise policy should be applied at the array level:

  • Enterprise policy only. In this case, the administrator at the enterprise level dictates that only the selected enterprise policy applies. No rules can be created.
  • Combined enterprise and array policy. In this case, an array policy is added to the enterprise policy. The enterprise policy overrides the array policy. That is, the array policy can impose additional limitations, but cannot be more permissive than the enterprise policy. You can use policy elements from the Enterprise and the Array,with the exception of protocols, that can only be taken from the Enterprise. Note that the FPCArrayPolicy object represents an access policy and the ISA Web proxy properties, but does not include the publishing rules of an array policy.
  • Array policy only. In this case, no enterprise policy is applied to the array. The array administrator can create any rule — rules that allow or deny access. You can only access the array's policy elements.

Note If you set the FPCEnterprise.PolicyUsedFlag property equal to fpcArrayPolicyUsed, you cannot subsequently change it to fpcEnterprisePolicyUsed, nor can you change to configuration from fpcEnterprisePolicyUsed to fpcArrayPolicyUsed. The only changes that are permitted are from fpcEnterprisePolicyUsed to fpcArrayAndEnterprisePoliciesUsed and from fpcArrayAndEnterprisePoliciesUsed to fpcEnterprisePolicyUsed.

The areas where the relationship between enterprise and array should be taken into consideration are:

  • Protocol Rules
  • Packet Filtering
  • Site and Content Rules
  • Publishing Rules

Protocol Rules

When you create a protocol rule for an array, you can only use a protocol that is defined in the enterprise. If you use any other protocol, you will receive an error message when you run the protocol rule-adding script, and the rule will not be added.

The COM object you use to create a protocol rule is FPCProtocolRule.

Packet Filtering

Packet filtering cannot be enabled at the enterprise level. However, the enterprise administrator determines whether packet filtering is forced at the array level. Alternatively, the enterprise administrator can allow the array administrator to decide if packet filtering should be made available.

If the enterprise administrator forces packet filtering through the FPCEnterprise.ForcePacketFiltering property, an array administrator will not be able to disable packet filtering through the FPCIpPacketFilter.Enabled property.

The COM object you use to create a packet filter is FPCIpPacketFilter.

Site and Content Rules

Because array policy can only be more restrictive than enterprise policy, you can only add array site and content rules that deny access to what is already allowed by the enterprise, or rules that redirect requests. The COM object you use to create a site and content rule is FPCSiteAndContentRule. You create a Deny rule by setting the FPCSiteAndContentRule.Action property equal to fpcRuleActionDeny. You create redirect rules by setting the FPCSiteAndContentRule.Action property to fpcRuleActionRedirect. If you try to create an allow (fpcRuleActionPermit ) site and content rule, you will receive an error message, and the rule will not be created.

Publishing Rules

Publishing rules cannot be created at the enterprise level. However, the enterprise administrator can specify, using the FPCEnterprise.AllowPublishing property, whether an array is allowed to publish servers. If the array is allowed to publish, the array administrator can create Web publishing rules (FPCWebPublishingRule object) or server publishing rules (FPCServerPublishingRule object). If the enterprise policy does not allow publishing, then an attempt to add a Web or server publishing rule will return an error message.


Add a New ISA Enterprise Policy

An ISA enterprise policy is represented by the FPCEnterprisePolicy object and the enterprise policy interfaces are accessed through the FPCEnterprise object. The FPCEnterprisePolicies.Add method adds a new ISA policy:

Dim objFPC As New FPCLib.FPC
Dim MyPolicies As FPCEnterprisePolicies
Dim MyPolicy As FPCEnterprisePolicy
Set MyPolicy = objFPC.Enterprise.EnterprisePolicies.Add("Standard Company Policy")
MyPolicy.Description = "Standard policy for all users"
'save your changes
MyPolicy.Save


Scenarios

The following sections describe administrative scenarios and how to complete the tasks involved by using the ISA administration COM objects.

  • Creating and Applying Enterprise Policy to an Array
  • Secure Web Hosting
  • Create and Update a Scheduled Content Download
  • Assign a Server Certificate from Local Computer Storage to an IP Address
  • Assign a Client Certificate to a Publishing Rule
  • Firewall Scenario
  • Web Publishing


Creating and Applying Enterprise Policy to an Array

The scenario describes the steps to take to create an enterprise policy and apply it to the enterprise or to an entire corporation. In this example, the enterprise has two branch offices, branch 1 and branch 2, each represented by an array of ISA servers.

For this example, you can assume that the corporation headquarters office policy states that employees in all branch offices are allowed HTTP access to all sites, and that the branch 1 policy allows HTTP access to members of the sales team only.

To create the enterprise policy

Follow these steps to create an enterprise policy. Both Visual Basic and VBScript code are provided

  1. Create a new enterprise policy, called "HQ" (headquarters).

    Visual Basic Code:

    Dim objFPC As New FPCLib.FPC
'Add new policy to the enterprise policies collection
Set objPolicy = objFPC.Enterprise.EnterprisePolicies.Add ("HQ")
'Save Changes to the root object
objFPC.Save

    VBScript Code:

    Set objFPC  = CreateObject ("FPC.Root")
Set objPolicy = objFPC.EnterprisePolicies.Policies.Add ("HQ")
objFPC.Save
  2. Add a protocol rule that allows HTTP requests to the new "HQ" policy.

    Visual Basic Code:

    Dim objFPC As New FPCLib.FPC
Dim NewProtocolRule As FPCProtocolRule
Dim EnterprisePolicy As fpcEnterprisePolicy
' get new policy "HQ"
Set NewEnterprisePolicy = objFPC.Enterprise.EnterprisePolicies.Policies("HQ")
Set NewProtocolRule = NewEnterprisePolicy.ProtocolRules.Add("Branch 1 Rule")
NewProtocolRule.Save

    VBScript Code:

    Set objFPC  = CreateObject ("FPC.Root")
Set NewEnterprisePolicy = objFPC.Enterprise.EnterprisePolicies.Policies("HQ")
Set NewProtocolRule = NewEnterprisePolicy.ProtocolRules.Add("Branch 1 Rule")
NewProtocolRule.Save

To create an array policy for Branch 1 and implement the enterprise policy

These steps will apply the headquarters policy to Branch 1, and create a local policy to allow HTTP access to employees in the sales department only.

  1. Enable the HQ enterprise policy.
  2. Create a protocol rule that denies HTTP access to a client set that includes all users except those from the sales department.

    Visual Basic Code:

    Dim objFPC As New FPCLib.FPC
Dim NewProtocolRule As FPCProtocolRule
Dim MyProtocolRefs As FPCRefs
Dim MyClientSets As FPCRefs
Set NewProtocolRule = objFPC.Enterprise.EnterprisePolicies.Policies(1).ProtocolRules.Add("HTTP Allow")
NewProtocolRule.Action = fpcActionDeny
NewProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
Set MyProtocolRefs = NewProtocolRule.SpecifiedProtocols
MyProtocolRefs.Add "HTTP", "", fpcEnterpriseScope
Set MyClientSets = NewProtocolRule.ClientAddressSetsUsed
MyClientSets.Add "Non Sales Team", "", fpcEnterpriseScope
objFPC.Save

    VBScript Code:

    'Define the enumerated type values
const fpcActionDeny = 1
const fpcSpecifiedProtocols = 1
const fpcEnterpriseScope = 1
Set objFPC  = CreateObject ("FPC.Root")
Set NewProtocolRule = objFPC.Enterprise.EnterprisePolicies.Policies(1).ProtocolRules.Add("HTTP Allow")
NewProtocolRule.Action = fpcActionDeny
NewProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
Set MyProtocolRefs = NewProtocolRule.SpecifiedProtocols
MyProtocolRefs.Add "HTTP", "", fpcEnterpriseScope
Set MyClientSets = NewProtocolRule.ClientAddressSetsUsed
MyClientSets.Add "Non Sales Team", "", fpcEnterpriseScope
objFPC.Save


Secure Web Hosting

Secure Web hosting (reverse proxying) refers to the ability of ISA Server to process incoming Web requests and forward them to an internal Web server, in the case of HTTP requests and to respond on the server's behalf. Requests are forwarded to an internal Web server, located behind the ISA server.

Web publishing rules filter all incoming and outgoing requests through the ISA server, and therefore determine how secure Web hosting functions. Web publishing rules define the mapping between incoming requests and the appropriate Web servers.

Note To publish non-Web servers such as ftp or SQL servers, use server publishing rules.

Example

This example lets you give a group of external customers access to an internal Web site, whose external domain name is www.microsoft.com/external.

To provide intranet access to an external user group

  1. To fully secure your network, enable dynamic packet filtering by using the FPCIpPacketFilters collection.
  2. Create a new destination set including www.microsoft.com/external. See Add a Destination Set.
  3. Create a new FPCWebPublishingRule that redirects external requests.
  4. Add a new FPCClientAddressSet object that defines a set including all external customers.
  5. Set the FPCWebPublishingRule.ClientAddressSetsUsed property to be the client address set that includes all external customers.
  6. Set the FPCWebPublishingRule.Action property to Redirect to the internal Web server.


Create and Update a Scheduled Content Download

The following VBScript code example creates and updates a scheduled content download operation.

' script creates and updates a scheduled content download operation with
' depth = 9, TaskPeriod = fpcDownloadOnSpecifiedDaysOfWeek and
' DaysOfWeek = Everyday.
' Syntax:
' Scheduled-Content-Download-Job.vbs ArrayName URL JobName
'

'<HTML><BODY>'<script language="VBScript">
'

Function TimeToStr( iHour, iMinute )
    Dim Hour, Minute
    ' format hour
    If iHour < 10 Then
        Hour = "0" & FormatNumber(iHour,0,-1,0,-1)
    Else
        Hour = FormatNumber(iHour,0,-1,0,-1)
    End If
    If iMinute < 10 Then
        Minute = "0" & FormatNumber(iMinute,0,-1,0,-1)
    Else
        Minute = FormatNumber(iMinute,0,-1,0,-1)
    End If
    TimeToStr = Hour & ":" & Minute
End Function

Sub AddScheduledContentDownloadJob()
    Set args = Wscript.Arguments

    ' get FPC arrays object
    Set objFPC = CreateObject("FPC.Root")
    objFPC.Refresh
    Set objArrays = objFPC.Arrays

    output = ""

    ' check that we have seven arguments
    If args.Count <> 7 Then
        ' Show syntax
        output = "Invalid parameters" & vbCrLf & _
               "Syntax:" & vbCrLf & _
               "    Scheduled-Content-Download-Job.vbs <ArrayName | .> JobName URL depth limit hour minute"
    End If

    ' Get the specified ISA array
    If args.Count = 0 Then
        output = output & vbCrLf & vbCrLf & "List of arrays:" & vbCrLf
        for each objArray in objArrays
            output = output & "    " & objArray.Name & vbCrLf
        Next
    else
        ArrayName = args(0)
        If ArrayName = "." Then             ' get the local array
            Set objArray = objArrays.GetContainingArray
            ArrayName = objArray.Name
        Else
            Set objArray = objArrays(ArrayName)
            If Err.Number <> 0 Then         ' specified array is not available
                Wscript.Echo "The specified array was not found"
                Exit Sub
            End If
        End If

        ' Array found
        Set DownloadContainer = objArray.Cache.ScheduledContentDownload

        If args.Count = 1 Then
            output = output & vbCrLf & vbCrLf & "List of Jobs:" & vbCrLf
            for each Job in Downloadcontainer
                output = output & "    " & Job.Name & " - " & Job.URL & "  @ " & TimeToStr( Job.SchedTimeHour, Job.SchedTimeMinute) & " (" & Job.MaxDepth & "/" & FormatNumber(Job.MaxPages,0,-1,0,-1) & ")" & vbCrLf
            Next
        else

            ' look for the job
            On Error Resume Next            ' set error handling
            set MyJob = Downloadcontainer.Item(args(1))
            If Err.Number <> 0 Then         ' Add the job
                set MyJob = Downloadcontainer.Add(args(1), args(2))
            End If
            On Error GoTo 0                 ' reset error handling

            If args.Count = 2 Then          ' 2 args display the job information
                output = output & vbCrLf & vbCrLf & "Job parameters:"

                ' get job parameters:
                output = output & vbCrLf & "    Name: " & MyJob.Name
                output = output & vbCrLf & "    URL: " & MyJob.URL
                output = output & vbCrLf & "    MaxDepth: " & MyJob.MaxDepth
                output = output & vbCrLf & "    MaxPages: " & FormatNumber(MyJob.MaxPages,0,-1,0,-1)

                ' scheduling
                output = output & vbCrLf & "    Runs at: " & MyJob.SchedTimeHour & ":" & FormatNumber(MyJob.SchedTimeMinute,0,-1,0,0)

            ' we have all the parameters, update the Job
            else
                If args.Count = 7 Then

                    If Err.Number <> 0 Then
                        Wscript.Echo "An error has occurred while creating job" & args(1) & vbCrLf & "    Error: " & Err.Description
                        Exit Sub
                    End If

                    ' set job parameters:
                    MyJob.Name = args(1)
                    MyJob.URL = args(2)
                    MyJob.Enabled  = true
                    MyJob.MaxDepth = args(3)
                    MyJob.MaxPages = args(4)
                    MyJob.StayInDomain = true

                    ' set scheduling
                    MyJob.SchedTimeHour = args(5)
                    MyJob.SchedTimeMinute = args(6)
                    MyJob.SetTaskPeriod 2, 127                  ' One fetch per day

                    ' set FetchUrlFlags:
                    MyJob.FetchUrlFlagForce = true
                    MyJob.FetchUrlFlagTtlOverride = false       ' use original expiration
                    MyJob.FetchUrlFlagTtlIfNone = false  ' bugbug true          ' set expiration if not available
                    MyJob.TTL = 24*60                           ' expires after 24 hours

                    ' Save
                    DownloadContainer.Save
                    If Err.Number <> 0 Then
                        Wscript.Echo "An error has occurred:" & vbCrLf & Err.Description
                    Else
                        Wscript.Echo "Scheduled content download job successfully created/updated"
                    End If
                    Exit Sub        ' out we go
                End If
            End If
        End If
    End If

    ' display message
    Wscript.Echo output

End Sub

AddScheduledContentDownloadJob

'</script></BODY></HTML>


Assign a Server Certificate from Local Computer Storage to an IP Address

The following VBScript example assigns an SSL server certificate from the local computer storage to an IP address by using the FPCServer object. After you run this script, the IP address on the computer where the certificate is stored will use the certificate for incoming Web requests.

call Install

Sub Install

        Set fpc = CreateObject("FPC.Root")
        Set CurServer = fpc.Arrays(1).Servers(1)
        NL = Chr(13) & Chr(10)
        TAB = Chr(9)
        Set certs = CurServer.SSLServerCertificates
        Dim i
        i = 1
        Dim certificates
        certificates = ""
        For Each cert In certs
            certificates = certificates & _
            i & ":" & NL & _
                "Friendly Name:" & TAB & cert.FriendlyName &   NL & _
            "Issued To:"     & TAB & cert.IssuedTo &       NL & _
                "Issued By:"     & TAB & cert.IssuedBy &       NL & _
                    "Expires at:"    & TAB & cert.ExpirationDate & NL
            i = i + 1
        Next

        Dim n
        n = InputBox(certificates & "Which certificate do you choose?", "Choose A Server Certificate")
        n = CInt(n)
        if not n > 0 and n < i then
                MsgBox "You chose a wrong number (" & n & ")" & NL & _
                       "Choose a number between 1 and " & i - 1
                Exit Sub
        end if

        Set cert = CurServer.SSLServerCertificates(n)

        MsgBox "You chose " & n & ":" & NL & _
               "Friendly Name:" & TAB & cert.FriendlyName & NL &_
               "Issued To:"     & TAB & cert.IssuedTo & NL & _
               "Issued By:"     & TAB & cert.IssuedBy & NL & _
               "Expires at:"    & TAB & cert.ExpirationDate

        CurServer.ReverseProxyListenEntries.AllSSLServerCertificate = cert
        CurServer.ReverseProxyListenEntries.Save
        MsgBox "done"
End Sub


Assign a Client Certificate to a Publishing Rule

The following VBScript code example assigns a client certificate to a publishing rule.

Example

call Install

Sub Install
        Set fpc = CreateObject("FPC.Root")
        Set CurServer = fpc.Arrays(1).Servers(1)
        NL = Chr(13) & Chr(10)
        TAB = Chr(9)
        Set certs = CurServer.SSLClientCertificates
        Dim i
        i = 1
        Dim certificates
        certificates = ""
        For Each cert In certs
            certificates = certificates & _
                i & ":" & TAB & cert.FriendlyName & NL & _
                          TAB & cert.IssuedTo & NL & _
                          TAB & cert.IssuedBy & NL & _
                          TAB & cert.ExpirationDate & NL & NL
            i = i + 1
        Next

        Dim n

        n = InputBox(certificates & "Which certificate do you choose?", "Choose A Client Certificate")

        if not n > 0 and n < i then
                MsgBox "You chose a wrong number (" & n & ")" & NL & _
                       "Choose a number between 1 and " & i - 1
                Exit Sub
        end if

        Set cert = CurServer.SSLClientCertificates(n)

        MsgBox "You chose " & n & ":" & NL & _
               "Friendly Name:" & TAB & cert.FriendlyName & NL &_
               "Issued To:"     & TAB & cert.IssuedTo & NL & _
               "Issued By:"     & TAB & cert.IssuedBy & NL & _
               "Expires at:"    & TAB & cert.ExpirationDate

        Set rules = fpc.Arrays(1).Publishing.WebPublishingRules

        i = 1
        Dim PubRules
        PubRules = ""
        For each rule in rules
            PubRules = PubRules & _
                i & ":" & TAB & rule.Name & NL & NL
            i = i + 1
        Next

        n = InputBox(PubRules & "Which publish rule do you choose?", "Choose a publish rule")
        if not n > 0 and n < i - 2 then
                MsgBox "You chose a wrong number (" & n & ")" & NL & _
                       "Choose a number between 1 and " & i - 2
                Exit Sub
        end if

        Set rule = fpc.Arrays(1).Publishing.WebPublishingRules(CInt(n))

        MsgBox "You chose " & m & ":" & NL & _
               "Name:" & TAB & rule.Name

        rule.SSLClientCertificate = cert
        rule.Save

        MsgBox "done"

End sub


Firewall Scenario

This scenario describes deployment of Microsoft Internet Security and Acceleration (ISA) Server as a dedicated firewall. The procedures and VBScript examples provided in this topic parallel the Firewall Scenario of the ISA product documentation, in which a similar configuration is created through ISA Management.

Network configuration

In the small office network configuration, the ISA Server computer can be placed between the corporate local area network (LAN)/wide area network (WAN) and the Internet. A small office network might have fewer than 250 clients on a single LAN segment, use the Internet protocol (IP) network protocol, and demand-dial connectivity to an Internet service provider. A single ISA Server computer can provide Internet connectivity and security for the entire network, as shown in the figure.

The scenario illustrated here and described as follows assumes a small organization, so the array contains just one ISA Server computer. To allow for future expansion, the server is set up as an array member. For more information, see Enterprise and Array Policy.

In a slightly larger organization, an array of ISA Server computers might be set up. Assuming that most of the clients are located on a single site and in a single domain, one ISA Server array can be set up to serve the entire organization. The array can contain one or more ISA Server computers, depending on bandwidth and cache requirements.

Setting up clients

Firewall Client software can be installed and made available on client desktops in the organization to ensure secured access for Winsock applications. Only Firewall Clients can be identified and fully authenticated by ISA Server, which can process rules on a per-user basis. For example, a site and content rule might limit access to a particular authenticated user; in this case, only Firewall clients can be granted access. For more information, see Restricting Site Access or the ISA product documentation.

If the organization does not want to deploy client software to all its users, the users can be set up as secure network address translation (SecureNAT) clients. For more information on SecureNAT clients, see Secure Network Address Translation.

For Web Proxy clients, the Web browsers are configured so that the proxy server is the ISA Server computer or ISA Server array. The proxy server port on the Web browser should be set to 8080—assuming that the ISA Server computer's outgoing Web request settings are also set to listen on port 8080.

If the desktop users have the Firewall Client software installed, then the Web browser need not be set up as a Web Proxy client. Instead, HTTP requests are forwarded to the ISA Server computer, which determines whether access is allowed. If it is, then the HTTP redirector filter, installed as part of ISA Server, forwards the request to the Web Proxy Service, which determines whether the requested object is in the cache.

In this scenario, the ISA Server computer is set up by using the automatic dial-out feature of ISA Server. The ISA Server computer also has a network card connected to the internal network.


Configuring the ISA Server policy for the organization

After setting up the server, the administrator considers the organization's business needs — who requires access to the Internet. These needs are mapped to an ISA Server policy, which the administrator configures either by scripting or by using ISA Management. For this example, assume that the corporation includes three departments: Sales, Research and Development, and Human Resources. The organization stipulates that Sales and Research and Development be allowed unlimited HTTP access, but only to a specific list of Web sites. The Human Resources department is allowed HTTP access after hours. In addition, all employees can access Windows media applications after hours, but at a lower bandwidth priority.

The administrator configures an array policy, creating a set of access policy rules that allow or limit access, in accordance with the scenario described above. The administrator follows the steps shown below to implement the policy.

Note The relevant portion of the administrator's script is shown for each step. Each portion could be run as an independent script because it creates the root object by using the code:

Set objFPC = CreateObject("FPC.root")

Each script also includes definitions of enumerated values. Where appropriate, each script creates an object "objMyArray" that is equal to the array on which the script is run:

Set objMyArray = objFPC.Arrays.GetContainingArray

If the script were to be run as a single script, you would only have to create the root object once, define each enumerated value once, and create the array object once. The complete firewall policy script is shown at the end of this topic.

  1. Set the enterprise policy default settings to Use array policy.
    Sub SetMyPolicy()
'Create the root object
Set objFPC = CreateObject("FPC.root")
objFPC.Enterprise.SetPolicy fpcArrayPolicyUsed
'save your changes
objFPC.Enterprise.Save
EndSub
SetMyPolicy
  2. Create a dial-up entry called Dial to My ISP, and make it the active entry.
    Sub NewDialUpEntry()
Set objFPC = CreateObject("FPC.root")
'Get the current array
Set objMyArray = objFPC.Arrays.GetContainingArray
'Add the dialup entry
Set objDialUpEntry = objMyArray.PolicyElements.DialupEntries.Add("Dial to My ISP", "Dialup Network Connection")
'Set the credentials for the dialup entry
Set objCredentials = objDialUpEntry.Credentials
objCredentials.UserName = "User Name"
objCredentials.Password = "Password"
'Set this entry as the active entry
objFPC.Arrays.GetContainingArray.PolicyElements.DialupEntries.ActiveEntry = "Dial to My ISP"
'Save the changes
objMyArray.Save
End Sub
NewDialUpEntry
  3. Create a routing rule with the following parameters:
    • Destination sets is All destinations.
    • Request action is Send directly to the Internet and Use this dial-up entry is set to Dial to My ISP.
    • Cache configuration is set to A valid version of the object.
    Sub RoutingRule()
const fpcAllDestinations = 0
const fpcPrimaryRouteDirect = 0
const fpcServeFromCacheIfValidObjectExists = 0
Set objFPC = CreateObject("FPC.Root")
Set objMyArray = objFPC.Arrays.GetContainingArray
'Get the routing rules collection
Set objRoutingRules = objMyArray.NetworkConfiguration.RoutingRules
'Add the new routing rule
Set objRoutingRule = objRoutingRules.Add("New Rule")
'Configure the new routing rule
objRoutingRule.SetDestination (fpcAllDestinations)
objRoutingRule.PrimaryRoute.RouteType = fpcPrimaryRouteDirect
objRoutingRule.UseCacheCondition = fpcServeFromCacheIfValidObjectExists
'Save the new rule
objRoutingRule.Save

EndSub
RoutingRule
  4. Configure Firewall chaining as follows:
    • Use primary connection is selected.
    • Automatic dial out when requests arrive is selected and the dial-up entry is set to Dial to My ISP (set with active entry in step 2).
    Sub FWChaining()

const fpcPrimaryConnection = 0
Set objFPC = CreateObject("FPC.Root")
Set objMyArray = objFPC.Arrays.GetContainingArray
'Create and configure the firewall chaining object
Set objFirewallChaining = objMyArray.NetworkConfiguration.FirewallChaining
objFirewallChaining.ForwardType = fpcPrimaryConnection
objFirewallChaining.ChainingAutoDialOut.EnableAutoDial = True
'Save the change
objFirewallChaining.Save

End Sub
FWChaining
  5. Create three client address sets, one for each of the departments. Each set should include the users or IP addresses for the department. Example ranges are used here.
    Sub ClientSets()

Set objFPC = CreateObject("FPC.Root")
Set MyClientSets = objFPC.Arrays.GetContainingArray.PolicyElements.ClientAddressSets
'Add the client address set for Sales
Set MyClientSet = MyClientSets.Add("Sales")
'Add a range of IP addresses to the client address set
Set MyClientSet = MyClientSet.Add("111.111.111.111", "111.111.111.115")
'Add the client address set for Research and Development
Set MyClientSet = MyClientSets.Add("Research and Development")
'Add a range of IP addresses to the client address set
Set MyClientSet = MyClientSet.Add("111.111.111.121", "111.111.111.125")
'Add the client address set for HR
Set MyClientSet = MyClientSets.Add("HR")
'Add a range of IP addresses to the client address set
Set MyClientSet = MyClientSet.Add("111.111.111.131", "111.111.111.135")

MyClientSets.SaveEnd Sub
ClientSets
  6. Create a schedule called After Hours.
    Sub NewSchedule()
Set objFPC  = CreateObject ("FPC.Root")
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.GetContainingArray.PolicyElements.Schedules
' Add new Schedule
Set objNewSchedule = MySchedules.Add("After Hours")
' Set the Schedule times to all week, after normal work hours
objNewSchedule.Set fpcALL_WEEK, fpcPM_5 - fpcAM_6
' save your changes
MySchedules.Save

End Sub
NewSchedule
  7. Create a bandwidth priority called Windows Media Bandwidth, with the outbound bandwidth and the inbound bandwidth set to 10.
    Sub BWPriority()

Set objFPC  = CreateObject ("FPC.Root")
'Get the bandwidth priority collection
Set BandwidthPriorities = objFPC.Arrays.GetContainingArray.PolicyElements.BandwidthPriorities
' Add new bandwidth priority
Set objNewBandwidthPriority = BandwidthPriorities.Add("Windows Media Bandwidth", 10, 10)
'Save your changes
BandwidthPriorities.Save

End Sub
BWPriority
  8. Create a protocol rule with the following settings:
    • The action is Allow.
    • The specified protocol is HTTP.
    • The schedule is Always.
    • The client type is Specific computers, and the specific client address sets are Sales and Research and Development.
    Sub ProtocolRule1()

Set objFPC  = CreateObject ("FPC.Root")
const fpcActionAllow = 0
const fpcAppliesToClientSets = 2
const fpcSpecifiedProtocols = 1
const fpcArrayScope = 0

Set objMyArray = objFPC.Arrays.GetContainingArray
'Get the protocol rules collection
Set ProtocolRules = objMyArray.ArrayPolicy.ProtocolRules
'Add a new protocol rule
Set ProtocolRule = ProtocolRules.Add ("HTTP Rule 1")
'Configure the rule
ProtocolRule.Action = fpcActionAllow
ProtocolRule.AppliesToMethod = fpcAppliesToClientSets
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
ProtocolRule.SpecifiedProtocols.Add ("HTTP")
ProtocolRule.SetAppliesAlways()
Set MyClientSets = ProtocolRule.ClientAddressSetsUsed
MyClientSets.Add "Sales", "", fpcArrayScope
MyClientSets.Add "Research and Development", "", fpcArrayScope
'Save the change
ProtocolRule.Save

End Sub
ProtocolRule1
  9. Create a protocol rule with the following settings:
    • The action is Allow.
    • The specified protocol is HTTP.
    • The schedule is After Hours.
    • The client type is Specific computers, and the specific client set is HR.
    Sub ProtocolRule2()

Set objFPC  = CreateObject ("FPC.Root")
const fpcActionAllow = 0
const fpcAppliesToClientSets = 2
const fpcSpecifiedProtocols = 1
const fpcArrayScope = 0

Set objMyArray = objFPC.Arrays.GetContainingArray
'Get the protocol rules collection
Set ProtocolRules = objMyArray.ArrayPolicy.ProtocolRules
'Add a new protocol rule
Set ProtocolRule = ProtocolRules.Add ("HTTP Rule 2")
'Configure the rule
ProtocolRule.Action = fpcActionAllow
ProtocolRule.AppliesToMethod = fpcAppliesToClientSets
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
ProtocolRule.SpecifiedProtocols.Add ("HTTP")
ProtocolRule.SetSchedule( "After Hours")
Set MyClientSets = ProtocolRule.ClientAddressSetsUsed
MyClientSets.Add "HR", "", fpcArrayScope
'Save the change
ProtocolRule.Save

End Sub
ProtocolRule2
  10. Create a protocol rule with the following settings:
    • The action is Allow.
    • The specified protocol is MMS - Windows Media Client.
    • The schedule is After Hours.
    • The client type is Any user, group, or client computer.
    Sub ProtocolRule3()

Set objFPC  = CreateObject ("FPC.Root")
const fpcActionAllow = 0
const fpcAppliesToAll = 0
const fpcSpecifiedProtocols = 1
const fpcArrayScope = 0

Set objMyArray = objFPC.Arrays.GetContainingArray
'Get the protocol rules collection
Set ProtocolRules = objMyArray.ArrayPolicy.ProtocolRules
'Add a new protocol rule
Set ProtocolRule = ProtocolRules.Add ("Windows Media Rule 2")
'Configure the rule
ProtocolRule.Action = fpcActionAllow
ProtocolRule.AppliesToMethod = fpcAppliesToAll
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
'To specify the Windows Media protocol, you need the GUID of the Streaming Media Filter
ProtocolRule.SpecifiedProtocols.Add "MMS - Windows Media","{473ED0E1-6371-4ED2-9F95-A676B66659A2}",fpcArrayScope
ProtocolRule.SetSchedule( "After Hours")
'Save the change
ProtocolRule.Save

End Sub
ProtocolRule3
  11. Create a site and content rule with the following settings:
    • Action is Allow.
    • Rule configuration is Custom.
    • The destination set is a Specified destination set and the specific set includes only the sites allowed by the corporate guidelines. In this example, the set is called "Approved Sites"
    • The schedule is Always.
    • The client type is Specific computers, and the specific client set is Sales and R&D.
    Sub DestinationSet()
'First create the destination set if it doesn't exist already
'This example includes a single site, so this rule could be very restrictive!
set objFPC = CreateObject  ("FPC.Root")
'Get the destination sets collection
Set MyFPCDestinationSets = objFPC.Arrays.GetContainingArray.PolicyElements.DestinationSets
'Add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Approved Sites")
'Add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("www.sports.microsoft.com")
MyFPCDestinationSets.Save
' save your changes
MyFPCDestinationSets.Save

End Sub
DestinationSet

Sub SiteAndContent()
'Now create the site and content rule
const fpcSpecifiedDestinationSet = 3
const fpcRuleActionPermit = 0
const fpcAppliesToClientSets = 2
const fpcArrayScope = 0

set objFPC = CreateObject  ("FPC.Root")
Set objMyArray = objFPC.Arrays.GetContainingArray
'Get the site and content rules collection
Set MySiteAndContentRules = objFPC.Arrays.GetContainingArray.ArrayPolicy.SiteAndContentRules

'Add new rule object
Set NewSiteAndContentRule = MySiteAndContentRules.Add("Site Restriction Rule")
'Configure the site and content rule
NewSiteAndContentRule.Description = "Allow only corporate-approved sites"
NewSiteAndContentRule.SetDestination fpcSpecifiedDestinationSet, "Approved Sites"
NewSiteAndContentRule.SetAppliesAlways
NewSiteAndContentRule.Action = fpcRuleActionPermit
NewSiteAndContentRule.AppliesToMethod = fpcAppliesToClientSets

Set MyClientSets = NewSiteAndContentRule.ClientAddressSetsUsed
MyClientSets.Add "Sales", "", fpcArrayScope
MyClientSets.Add "Research and Development", "", fpcArrayScope
' save your changes

MySiteAndContentRules.Save

End Sub
SiteAndContent
  12. Create a bandwidth rule with the following settings:
    • The selected protocol is MMS - Windows Media client.
    • The schedule is After Hours.
    • Applies to Any request.
    • The destination is All destinations.
    • The client type is Any user, group, or client computer.
    • The destination set is All destinations.
    • The content group is All content groups.
    • The bandwidth priority is set to a Custom class Windows Media Bandwidth.
    Sub BWRule()

const fpcSpecifiedProtocols = 1
const fpcAllDestinations = 0
const fpcAppliesToAll = 0
const fpcAppliesToAllContent = 0

set objFPC = CreateObject  ("FPC.Root")
Set objMyArray = objFPC.Arrays.GetContainingArray
'Get the bandwidth rules collection
Set BandwidthRules = objMyArray.BandwidthRules
'Add a rule
Set BandwidthRule = BandwidthRules.Add("Bandwidth Rule 1")
'The following seven lines define the bandwidth rule
BandwidthRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
BandwidthRule.SpecifiedProtocols.Add "MMS - Windows Media", "{473ED0E1-6371-4ED2-9F95-A676B66659A2}", fpcArrayScope
BandwidthRule.SetSchedule ("After Hours")
BandwidthRule.SetDestination (fpcAllDestinations)
BandwidthRule.AppliesToMethod = fpcAppliesToAll
BandwidthRule.AppliesToContentMethod = fpcAppliesToAllContent
BandwidthRule.SetBandwidthPriority False, "Windows Media Bandwidth"
'Save the rule
BandwidthRule.Save

End Sub
BWRule


Firewall Policy Script

The VBScript script that combines all of the steps in Configuring the ISA Server policy for the organization is shown in the following code.

Sub FirewallPolicy()
'Set the enterprise policy default settings to Use array policy.
'Set all of the enum constants that are used in the script
const fpcArrayPolicyUsed = 0
const fpcAllDestinations = 0
const fpcPrimaryRouteDirect = 0
const fpcServeFromCacheIfValidObjectExists = 0
const fpcPrimaryConnection = 0
const fpcActionAllow = 0
const fpcAppliesToClientSets = 2
const fpcSpecifiedProtocols = 1
const fpcArrayScope = 0
const fpcAppliesToAll = 0
const fpcSpecifiedDestinationSet = 3
const fpcRuleActionPermit = 0
const fpcAppliesToAllContent = 0

'Create the root object
Set objFPC = CreateObject("FPC.root")
objFPC.Enterprise.SetPolicy fpcArrayPolicyUsed
  'save your changes
objFPC.Enterprise.Save
'MyPolicies.Save

'Create a dial-up entry called Dial to My ISP and make it the active entry.
'Get the current array
Set objMyArray = objFPC.Arrays.GetContainingArray
'Add the dialup entry
Set objDialUpEntry = objMyArray.PolicyElements.DialupEntries.Add("Dial to My ISP", "Dialup Network Connection")
'Set the credentials for the dialup entry
Set objCredentials = objDialUpEntry.Credentials
objCredentials.UserName = "User Name"
objCredentials.Password = "Password"
'Set this entry as the active entry
objFPC.Arrays.GetContainingArray.PolicyElements.DialupEntries.ActiveEntry = "Dial to My ISP"
'Save the changes
objMyArray.Save

'Create the routing rule
'Get the routing rule collection
Set objRoutingRules = objMyArray.NetworkConfiguration.RoutingRules
'Add the new routing rule
Set objRoutingRule = objRoutingRules.Add("New Rule")
'Configure the new routing rule
objRoutingRule.SetDestination (fpcAllDestinations)
objRoutingRule.PrimaryRoute.RouteType = fpcPrimaryRouteDirect
objRoutingRule.UseCacheCondition = fpcServeFromCacheIfValidObjectExists
'Save the new rule
objRoutingRule.Save

'Create and configure the firewall chaining object
Set objFirewallChaining = objMyArray.NetworkConfiguration.FirewallChaining
objFirewallChaining.ForwardType = fpcPrimaryConnection
objFirewallChaining.ChainingAutoDialOut.EnableAutoDial = True
'Save the change
objFirewallChaining.Save

'Create three client address sets, one for each of the departments.

Set MyClientSets = objFPC.Arrays.GetContainingArray.PolicyElements.ClientAddressSets
'Add the client address set for Sales
Set MyClientSet = MyClientSets.Add("Sales")
'Add a range of IP addresses to the client address set
Set MyClientSet = MyClientSet.Add("111.111.111.111", "111.111.111.115")
'Add the client address set for Research and Development
Set MyClientSet = MyClientSets.Add("Research and Development")
'Add a range of IP addresses to the client address set
Set MyClientSet = MyClientSet.Add("111.111.111.121", "111.111.111.125")
'Add the client address set for HR
Set MyClientSet = MyClientSets.Add("HR")
'Add a range of IP addresses to the client address set
Set MyClientSet = MyClientSet.Add("111.111.111.131", "111.111.111.135")

MyClientSets.Save

'Create a schedule called After Hours.
' get the schedule collection of the current array
Set MySchedules = objFPC.Arrays.GetContainingArray.PolicyElements.Schedules
' Add new Schedule
Set objNewSchedule = MySchedules.Add("After Hours")
' Set the Schedule times to all week, after normal work hours
objNewSchedule.Set fpcALL_WEEK, fpcPM_5 - fpcAM_6
' save your changes
MySchedules.Save

'Create a bandwidth priority called Windows Media Bandwidth
'Get the bandwidth priority collection
Set BandwidthPriorities = objFPC.Arrays.GetContainingArray.PolicyElements.BandwidthPriorities
' Add new bandwidth priority
Set objNewBandwidthPriority = BandwidthPriorities.Add("Windows Media Bandwidth", 10, 10)
'Save your changes
BandwidthPriorities.Save

'Create the first protocol rule
'Get the protocol rules collection
Set ProtocolRules = objMyArray.ArrayPolicy.ProtocolRules
Set ProtocolRule = ProtocolRules.Add ("HTTP Rule 1")
'Configure the rule
ProtocolRule.Action = fpcActionAllow
ProtocolRule.AppliesToMethod = fpcAppliesToClientSets
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
ProtocolRule.SpecifiedProtocols.Add ("HTTP")
ProtocolRule.SetAppliesAlways()
Set MyClientSets = ProtocolRule.ClientAddressSetsUsed
MyClientSets.Add "Sales", "", fpcArrayScope
MyClientSets.Add "Research and Development", "", fpcArrayScope
'Save the change
ProtocolRule.Save

'Add the second protocol rule
Set ProtocolRule = ProtocolRules.Add ("HTTP Rule 2")
'Configure the rule
ProtocolRule.Action = fpcActionAllow
ProtocolRule.AppliesToMethod = fpcAppliesToClientSets
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
ProtocolRule.SpecifiedProtocols.Add ("HTTP")
ProtocolRule.SetSchedule( "After Hours")
Set MyClientSets = ProtocolRule.ClientAddressSetsUsed
MyClientSets.Add "HR", "", fpcArrayScope
'Save the change
ProtocolRule.Save

'Add the third protocol rule
Set ProtocolRule = ProtocolRules.Add ("Windows Media Rule")
'Configure the rule
ProtocolRule.Action = fpcActionAllow
ProtocolRule.AppliesToMethod = fpcAppliesToAll
ProtocolRule.Enabled = True
ProtocolRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
'To specify the Windows Media protocol, you need the GUID of the Streaming Media Filter
ProtocolRule.SpecifiedProtocols.Add "MMS - Windows Media","{473ED0E1-6371-4ED2-9F95-A676B66659A2}",fpcArrayScope
ProtocolRule.SetSchedule( "After Hours")
'Save the change
ProtocolRule.Save

'Create the destination set if it doesn't exist already
'This example includes a single site, so this rule could be very restrictive!
'Get the destination sets collection
Set MyFPCDestinationSets = objFPC.Arrays.GetContainingArray.PolicyElements.DestinationSets
'Add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Approved Sites")
'Add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("www.sports.microsoft.com")
MyFPCDestinationSets.Save
' save your changes
MyFPCDestinationSets.Save

'Create the site and content rule
'Get the site and content rules collection
Set MySiteAndContentRules = objFPC.Arrays.GetContainingArray.ArrayPolicy.SiteAndContentRules

'Add new rule object
Set NewSiteAndContentRule = MySiteAndContentRules.Add("Site Restriction Rule")
'Configure the site and content rule
NewSiteAndContentRule.Description = "Allow only corporate-approved sites"
NewSiteAndContentRule.SetDestination fpcSpecifiedDestinationSet, "Approved Sites"
NewSiteAndContentRule.SetAppliesAlways
NewSiteAndContentRule.Action = fpcRuleActionPermit
NewSiteAndContentRule.AppliesToMethod = fpcAppliesToClientSets

Set MyClientSets = NewSiteAndContentRule.ClientAddressSetsUsed
MyClientSets.Add "Sales", "", fpcArrayScope
MyClientSets.Add "Research and Development", "", fpcArrayScope
' save your changes

MySiteAndContentRules.Save

'Create the bandwidth rule

'Get the bandwidth rules collection
Set BandwidthRules = objMyArray.BandwidthRules
'Add a rule
Set BandwidthRule = BandwidthRules.Add("Bandwidth Rule 1")
'The following seven lines define the bandwidth rule
BandwidthRule.ProtocolSelectionMethod = fpcSpecifiedProtocols
BandwidthRule.SpecifiedProtocols.Add "MMS - Windows Media", "{473ED0E1-6371-4ED2-9F95-A676B66659A2}", fpcArrayScope
BandwidthRule.SetSchedule ("After Hours")
BandwidthRule.SetDestination (fpcAllDestinations)
BandwidthRule.AppliesToMethod = fpcAppliesToAll
BandwidthRule.AppliesToContentMethod = fpcAppliesToAllContent
BandwidthRule.SetBandwidthPriority False, "Windows Media Bandwidth"
'Save the rule
BandwidthRule.Save

End Sub
FirewallPolicy


Web Publishing

This scenario parallels the Web server on local network scenario of the ISA product documentation, in which a similar configuration is created through ISA Management.

The following illustration show a Web publishing scenario, with the Web servers located behind the Microsoft Internet Security and Acceleration (ISA) Server computer.

Two Web servers are located on the internal network, which is protected by ISA Server. When an Internet user requests an object on example.microsoft.com\Marketing or example.microsoft.com\Development, the request is actually sent to the ISA Server computer, which routes the request to the appropriate Web server.

Notice that when external clients request objects from Web servers, they actually gain access to the ISA Server computer. This way, ISA Server ensures that the network is never penetrated by external users. Furthermore, the Internet protocol (IP) addresses of the Web servers are never exposed. Instead, the Internet users gain access to the Web servers by specifying the ISA Server computer's IP address.

Suppose you want to publish two internal servers on the example.microsoft.com domain, one called Dev and one called Mktg. The Mktg computer should return objects when a client requests example.microsoft.com/Marketing, and Dev should return objects when a client requests example.microsoft.com/Development.

Note The relevant portion of the administrator's script is shown for each step. Each portion could be run as an independent script because it creates the root object by using the code:

Set objFPC = CreateObject("FPC.root")

Each script also includes definitions of enumerated values. Where appropriate, each script creates an object "objArray" that is equal to the array on which the script is run:

Set objArray = objFPC.Arrays.GetContainingArray

If the script were to be run as a single script, you would only have to create the root object once, define each enumerated value once, and create the array object once. The complete Web publishing script is shown at the end of this topic.

Follow these steps to publish the Web servers.

  1. Verify that the DNS server maps the fully-qualified domain name to the IP address of the ISA Server computer. Internet clients use the domain name to request content.
  2. Configure the ISA Server incoming Web request properties. The IP address should include the IP address of the external interface, assumed to be 2.2.2.2 for the purposes of this example.
    Sub IncomingWeb()
'Create the root object
Set objFPC  = CreateObject ("FPC.Root")
'Get the current array
Set objArray = objFPC.Arrays.GetContainingArray
'Get the incoming Web request object
Set objWebRequest = objArray.ArrayPolicy.WebProxy.InComingWebRequests
'Tell the Web proxy not to listen on all interfaces.
objWebRequest.AllInterfaces = True
Set objServer = objArray.Servers.GetContainingServer
'The IP address must be that of an external interface
Set objListenEntry = objServer.ReverseProxyListenEntries.Add("2.2.2.2")
'Save your changes
objServer.Save
objListenEntry.Save
objWebRequest.Save

End Sub
IncomingWeb
  3. Create a destination set called Marketing, which should include the computer example.microsoft.com and the path \Marketing\*, and a destination set called Development, which should include the computer example.microsoft.com and the path \Development\*.
    Set objFPC  = CreateObject ("FPC.Root")
' set the destination sets to current array
Set MyFPCDestinationSets = objFPC.Arrays.GetContainingArray.PolicyElements.DestinationSets
' add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Marketing")
' add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("example.microsoft.com", , "/Marketing/")
'Set the path
MyFPCDestination.SetDestinationAsDomain "example.microsoft.com","/Marketing/"

' add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Development")
' add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("example.microsoft.com", , "/Development/")
'Set the path
MyFPCDestination.SetDestinationAsDomain "example.microsoft.com","/Development/"
' save your changes
MyFPCDestinationSets.Save
  4. Configure a Web publishing rule that has the following parameters:
    • Set Destination Set to the Marketing destination set.
    • Set Applies to to Any user, group, or client computer.
    • Set Action to Redirect to a hosted site and specify Mktg as the specified host.
    Sub PubRule1()
Set objFPC  = CreateObject ("FPC.Root")
const fpcRouteRedirect = 1
const fpcAppliesToAll = 0

Set objArray = objFPC.Arrays.GetContainingArray
'Get the publishing rules collection
Set PublishingRules = objArray.Publishing.WebPublishingRules
'Add the publishing rule
Set PublishingRule = PublishingRules.Add("Mktg redirect rule")
'Configure the rule
PublishingRule.SetWebSiteAndPorts fpcRouteRedirect, "Marketing"
PublishingRule.AppliesToMethod = fpcAppliesToAll
PublishingRule.Description = "Marketing Web publishing rule"
PublishingRule.Enabled = True
PublishingRule.Save
End Sub
PubRule1
  5. Configure the second Web publishing rule with the following parameters:
    • Set Destination Set to the Development destination set.
    • Set Applies to to Any user, group, or client computer.
    • Set Action to Redirect to a hosted site and specify Dev as the specified host.
    Sub PubRule2()
const fpcRouteRedirect = 1
const fpcAppliesToAll = 0

Set objArray = objFPC.Arrays.GetContainingArray
'Get the publishing rules collection
Set PublishingRules = objArray.Publishing.WebPublishingRules
'Add the publishing rule
Set PublishingRule = PublishingRules.Add("Development redirect rule")
'Configure the rule
PublishingRule.SetWebSiteAndPorts fpcRouteRedirect, "Development"
PublishingRule.AppliesToMethod = fpcAppliesToAll
PublishingRule.Description = "Marketing Web publishing rule"
PublishingRule.Enabled = True
PublishingRule.Save
End Sub
PubRule2


Web Publishing Script

The script that combines all of the steps in Web Publishing is shown in the following code.

Sub WebPublishing()
'Define the enumerated type values
const fpcRouteRedirect = 1
const fpcAppliesToAll = 0

'Create the root object
Set objFPC  = CreateObject ("FPC.Root")
'Get the current array
Set objArray = objFPC.Arrays.GetContainingArray
'Get the incoming Web request object
Set objWebRequest = objArray.ArrayPolicy.WebProxy.InComingWebRequests
'Tell the Web proxy not to listen on all interfaces.
objWebRequest.AllInterfaces = True
Set objServer = objArray.Servers.GetContainingServer
Set objListenEntry = objServer.ReverseProxyListenEntries.Add("2.2.2.2")
'Save your changes
objServer.Save
objListenEntry.Save
objWebRequest.Save
'Create the destination sets
' Get the destination sets collection
Set MyFPCDestinationSets = objArray.PolicyElements.DestinationSets
' add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Marketing")
' add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("example.microsoft.com", , "/Marketing/")
'Set the path
MyFPCDestination.SetDestinationAsDomain "example.microsoft.com","/Marketing/"

' add a new set to the collection
Set MyFPCDestinationSet = MyFPCDestinationSets.Add("Development")
' add a new destination to the set
Set MyFPCDestination = MyFPCDestinationSet.Add("example.microsoft.com", , "/Development/")
'Set the path
MyFPCDestination.SetDestinationAsDomain "example.microsoft.com","/Development/"
' save your changes
MyFPCDestinationSets.Save

'Configure the first Web publishing rule
'Get the publishing rules collection
Set PublishingRules = objArray.Publishing.WebPublishingRules
'Add the publishing rule
Set PublishingRule = PublishingRules.Add("Mktg redirect rule")
'Configure the rule
PublishingRule.SetWebSiteAndPorts fpcRouteRedirect, "Marketing"
PublishingRule.AppliesToMethod = fpcAppliesToAll
PublishingRule.Description = "Marketing Web publishing rule"
PublishingRule.Enabled = True
PublishingRule.Save

'Configure the second Web publishing rule
'Already have the collection, add the publishing rule
Set PublishingRule = PublishingRules.Add("Development redirect rule")
'Configure the rule
PublishingRule.SetWebSiteAndPorts fpcRouteRedirect, "Development"
PublishingRule.AppliesToMethod = fpcAppliesToAll
PublishingRule.Description = "Marketing Web publishing rule"
PublishingRule.Enabled = True
'Save changes to the collection
PublishingRules.Save
End Sub
WebPublishing


Script Samples

The ISA Server SDK provides example code to demonstrate the scripting capabilities of ISA. Sample administration scripts are provided on the CD-ROM in the folder SDK\samples\admin\scripts.

The scripts provided on the CD are:

  • Add_Dod
  • AddDeniedMethod
  • AdditionalKey
  • AddLATEntry
  • AddScheduledContentDownload
  • ApplicationFilterList
  • CacheSettings
  • ConstructLAT
  • DeleteURL
  • DisableScheduledContentDownload
  • Enterprise_Destination
  • FetchUrl
  • FindScheduledContentDownload
  • ListDeniedMethods
  • ListServers
  • SetCache
  • SetDefaultApplicationSettings
  • SetUpstreamRouting
  • ShowAllProtocolRules
  • ShowAllRoutingRules
  • StaticFilter


Add_Dod

Add_Dod is a VBScript sample that demonstrates how to add a new Dialup Entry and set the Dialup Entry Credentials. The script also sets one Routing rule to use the new Dialup Entry.


AddDeniedMethod

The AddDeniedMethod sample is a VBScript script that adds a denied HTTP method to an array by using the FPCDeniedMethods collection.


AdditionalKey

The AdditionalKey sample is a VBScript script that demonstrates how to change an additional key. The script changes the additional key for a service started event.


AddLATEntry

AddLATEntry is a VBScript sample that demonstrates how to add an IP range to a Local Address Table (LAT). This sample accesses the FPCLAT collection, which represents the LAT, and then adds an entry to the table through the FPCLAT.Add method.


AddScheduledContentDownload

AddScheduledContentDownload is a VBScript sample that receives an array name, a URL, and a job name, and adds a scheduled content download job with depth = 3, TaskPeriod = PrefetcherSpecifiedDaysOfWeek and DaysOfWeek = Sunday and Tuesday.


ApplicationFilterList

ApplicationFilterList is a sample that prompts the user to enter an array, and then it lists the application filters of the selected array. The application filter's name, version, and vendor are listed through use of the FPCApplicationFilters collection. Both VBScript and JScript samples are provided on the CD.


CacheSettings

CacheSettings is a sample that prompts the user to enter the name of an array, then displays the cache settings of that array. The settings include whether active caching is enabled, which cache drives are present in the array, and the total size of the cache. The listing of available drives and their sizes is obtained through properties of the FPCCacheDrives collection. You can obtain information regarding active caching status through the FPCCacheConfiguration object. Both VBScript and JScript samples are provided.


ConstructLAT

ConstructLAT is a sample that demonstrates how to construct the Local Address Table (LAT) of an array based on its network interface cards (NICs). The script goes through each NIC and asks the user whether it should be included in the LAT. The LAT is built based on user responses. Both VBScript and JScript samples are provided.


DeleteURL

DeleteURL is a VBScript sample that uses the FPCCacheContents.FetchUrl method to cause the Web proxy service to delete a Web object from the ISA cache.


DisableScheduledContentDownload

DisableScheduledContentDownloads is a VBScript sample that disables all scheduled content download jobs on Monday and Wednesday in a given array.


Enterprise_Destination

The Enterprise_Destination sample is a VBScript sample that adds a new Destination Set to the Enterprise, sets the array policy to use Array and Enterprise Policies, and configures the new rule to use the Enterprise Destination.

Only an enterprise administrator can run this script.


FetchUrl

FetchUrl is a VBScript sample that causes the Web proxy service to fetch an object and store it in the Web proxy service's cache. The Web proxy service can store the cached object under a different name than that of the source object. This script also allows you to specify how long the object should be considered "fresh" within the cache. This is done by setting the cached object's Time-to-Live (TTL) property.


FindScheduledContentDownload

The FindScheduledContentDownload sample is a VBScript that receives an array name and a URL and checks if any scheduled content download job includes that URL.


ListDeniedMethods

The ListDeniedMethods sample is a VBScript that lists all of the denied HTTP methods for an array by using the FPCDeniedMethods collection.


ListServers

ListServers is a sample that lists all the servers in a given array through the Name property of the FPCArray object. Both VBScript and JScript samples are provided.


SetCache

SetCache is a VBScript sample that configures cache settings. The script tells the user whether caching is enabled or disabled and allows that setting to be changed. The script then indicates whether active caching is enabled or disabled and allows that setting to be changed. You can access the caching and active caching settings through the FPCCacheConfiguration object.


SetDefaultApplicationSettings

SetDefaultApplicationSettings is a VBScript sample that demonstrates how to add client settings sections (FPCClientSettingsSection object) to the firewall client settings collection (FPCClientConfigSettings).


SetUpstreamRouting

SetUpstreamRouting is a VBScript sample that demonstrates how to set up upstream routing to another server by using the FPCRoutingRules collection and the FPCPrimaryRoute object. This script is based on command line arguments, and illustrates how to change routing rules by using the FPCRoutingRule object.


ShowAllProtocolRules

ShowAllProtocolRules is a sample that lists all the protocol rules of an array by looping through the FPCProtocolRules collection. Both VBScript and JScript samples are provided.


ShowAllRoutingRules

ShowAllRoutingRules is a VBScript sample that lists all the routing rules of an array by looping through the FPCRoutingRules collection. The script also lists whether or not each routing rule is enabled or disabled, and the action that the rule follows.


StaticFilter

StaticFilter is a VBScript sample that demonstrates how to add a static IP packet filter that allows Network Time Protocol (NTP) communication from the ISA Server computer to the Internet. NTP uses port 123, UDP protocol.


Extending ISA Management

ISA Management is designed to be extensible. One way that you can extend ISA Management is to use Microsoft® Management Console (MMC) extension snap-ins. The topic How to Create a Microsoft Management Console Snap-in provides general information on how to create an MMC snap-in for ISA, and an example MMC snap-in for an ISA application filter.

Any ISA node can be extended with a snap-in.

What Can Extension Snap-ins Extend?

Extension snap-ins can extend the following:

  • The name space by adding scope pane child nodes.
  • Context menus.
  • Toolbars and toolbar buttons.
  • Property pages.

For more information please refer to the MMC documentation.

There are several steps you need to take to create an extension snap-in.

To create an extension snap-in

  1. Define your schema in the FPCVendorParametersSet object.
  2. Write the code for the MMC snap-in.
  3. Store/retrieve the data in the FPCVendorParametersSet object retrieved by using the FPCSnapinNode.CurrentObject.VendorParametersSet property.

Each node of an ISA snap-in exposes its specific data to extension snap-ins by using the COM interface: IFPCSnapinNode. The interface contains four properties:

  • ParentArray (of type IDispatch)
  • CurrentObject (of type IDispatch)
  • ComRoot (of type IDispatch)
  • ParentPolicy (of type IDispatch)

The IFPCSnapinNode can be retrieved by querying the IDataObject interface of the ISA node that you want to extend. The ParentArray property is an FPCArray object as exposed through the ISA administration COM object model. Note that this property returns an error for the Root node of the ISA snap-in. The CurrentObject property is interface-specific to the node to be extended. See How to Create a Microsoft Management Console Snap-in for more details.

The ISA nodes that support MMC extensions and their GUIDs are listed in the Globally Unique Identifiers topic of the Reference section.


How to Create a Microsoft Management Console Snap-in

This section explains how to create property sheets. In describing the procedures and code needed to create the Microsoft Management Console (MMC) snap-in, this document uses the example of the Simple Mail Transfer Protocol (SMTP) filter created in How to Create an Application Filter.

You can use ISA Server to create application filters. After creating the application filters, you can use the Microsoft Management Console (MMC), described in MSDN, to modify the application filter properties in ISA Management.

This section contains the following topic:

  • Creating a Microsoft Management Console Snap-in for an Application Filter


Creating a Microsoft Management Console Snap-in for an Application Filter

To create a Microsoft Management Console (MMC) snap-in for an application filter you need to follow these steps, as described in the following sections:

  1. Create the property sheet. Initially, this property sheet will be displayed for all of the application filters.
  2. Test the property sheet extension.
  3. Limit the property sheet, so that it displays only on the relevant application filter.
  4. Design the property page layout.
  5. Create message handlers for the property sheet elements.
  6. Load filter configuration data from vendor parameter sets and display it in ISA Management.
  7. Save the configuration data from ISA Management to the vendor parameter set.


Creating the Property Sheet

Follow the procedure in this section to create the property sheet. This must be done on a computer that has the ISA administration tool installed.

To create the property sheet

  1. In Microsoft Visual C++® 6.0, on the File menu, click New.
  2. On the Projects tab, click ATL Com App Wizard.
  3. In the Project Name box, type SMTPFilterConfig.
  4. Click OK, then Finish.
  5. On the Insert menu, click New ATL Object…
  6. In the Objects list view, select MMC Snap-in.
  7. Click Next.
  8. On the Names tab, type SmtpFltrSnapIn in the ShortName box.
  9. On the MMC Snapin tab, select the Extension and IExtendPropertySheet check boxes. (Be sure to leave checked the following check boxes: IComponentData, IComponent, and ISnapInAbout).
  10. Clear the Support Persistence check box.
  11. On the MMC Snapin tab, in the Extends Node box, select ISA Application Filter.

    Warning Be sure not to select ISA Application Filters.

  12. Edit SmtpFltrSnapIn.cpp:

    Comment out the line

    if (type == CCT_SCOPE || type == CCT_RESULT)

    that is shown as a comment in the following code. This line appears several times in the code, so be certain to comment out the right line.

    HRESULT CSmtpFltrSnapInExtData::CreatePropertyPages(LPPROPERTYSHEETCALLBACK lpProvider,
    long handle,
    IUnknown* pUnk,
    DATA_OBJECT_TYPES type)
{
    // if (type == CCT_SCOPE || type == CCT_RESULT)
    {
        CSmtpFltrSnapInPage* pPage = new CSmtpFltrSnapInPage(handle, true, _T("SmtpFltrSnapIn"));
        lpProvider->AddPage(pPage->Create());
        // The second parameter to the property page class constructor
        // should be true for only one page.

        // TODO : Add code here to add additional pages
        return S_OK;
    }
    return E_UNEXPECTED;
}
  13. In SmtpFltrSnapIn.h, in the CSmtpFltrSnapInExtData class, comment out the line shown as a comment in the following code:
        STDMETHOD(QueryPagesFor)(DATA_OBJECT_TYPES type)
    {
        // if (type == CCT_SCOPE || type == CCT_RESULT)
            return S_OK;
        return S_FALSE;
    }
  14. Build.


Testing the Property Sheet Extension

Follow this procedure to test the new property sheet.

To test the new property sheet

  1. Run ISA Management (Click Start, point to Programs, point to Microsoft ISA Server, and then click ISA Management).
  2. Select the applicable array, select Extensions and then click Application Filters.
  3. Display the properties of any of the application filters listed in the details pane, by either double-clicking the name of the filter, or right-clicking and selecting Properties. Note that each of the application filters has a new property sheet called SmtpFltrSnapIn (and it is empty).


Limiting the Property Sheet Display

The property sheet should display only on the relevant application filter; in this case, on the SMTP application filter.

To limit the property sheet display

  1. Select a unique attribute name for the application filter; for example, its GUID.
  2. Add the directory of the file msfpccom.dll (SDK installation root\bin) to the include path.
  3. In Stdafx.h add the following #import statement:
    #import "msfpccom.dll" named_guids

    The #import directive is used to incorporate information from a type library. The content of the type library is converted into C++ classes, mostly describing the COM interfaces.

  4. In SmtpFilterSnapIn.cpp, add the code that is in bold font in the following sample to this method:
    HRESULT CSMTPFltrSnapInExtData::CreatePropertyPages(LPPROPERTYSHEETCALLBACK lpProvider,
    long handle,
    IUnknown* pUnk,
    DATA_OBJECT_TYPES type)
{
    FPCLib::IFPCSnapinNodePtr spiFPCSnapinNode(m_pDataObject);

    FPCLib::IFPCApplicationFilterPtr spiApplicationFilter(spiFPCSnapinNode->CurrentObject);

    _bstr_t bstrGUID(spiApplicationFilter->GetGuid());

    // if (type == CCT_SCOPE || type == CCT_RESULT)
    if (bstrGUID == _bstr_t("{179A0A70-1EF5-11D3-B160-00A0C9E3F998}"))  // Smtp Filter GUID
    {
                CSmtpFltrSnapInPage* pPage = new CSmtpFltrSnapInPage(handle, true, _T("SmtpFltrSnapIn"));lpProvider->AddPage(pPage->Create());
        // The second parameter to the property page class constructor
        // should be true for only one page.

        // TODO : Add code here to add additional pages
        return S_OK;
    }
    return E_UNEXPECTED;
}
  5. Build.
  6. Test. Run ISA Management. Notice that the property sheet appears only on the SMTP application filter.


Designing the Property Page Layout

Once you've succeeded in testing the property page, you can change its design.

To design the property page

  1. In Visual C++ 6.0, click the Resource View tab.
  2. Double-click the IDD_SmtpFilterSnapIn node in the Dialog section.
  3. Use the Controls floating menu to select the graphical elements to place on the page. For example, you may design the property page as follows:


Creating Message Handlers for the Property Sheet Elements

You need to add handlers to the design elements you have placed on the property page.

To create the message handlers

  1. Double-click a design element on the property page. The following dialog box displays.

  2. Select the design element name from the Class or object to handle list.
  3. Select the name of the event you want to handle (for example, the EN_CHANGE event).
  4. Click the Add and Edit button – this will generate the needed method specification and let you edit the code. For example, if you use the EN_CHANGE event in the IDC_VIRUS_STRING edit box, the following code will be generated:
    LRESULT OnChange_VirusString(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL& bHandled)
    {
        // TODO : Add Code for control notification handler.
        return 0;
    }
  5. You would like, at least, to enable the Apply button whenever a change to any of the controls is made. To do so you need to add the following code to the message handler:
        // Enable the Apply button
    SetModified();


Loading and Displaying the Filter Configuration

Note that the fields on the property page you will create are based on information extracted from FPCApplicationFilter.VendorParametersSets. The FPCApplicationFilter object is identified by the filter GUID, and is created when a user accesses the filter node in the ISA MMC snap-in. When the property page is created, it runs on a separate thread from that of the FPCApplicationFilter object. For this reason, part of the code provided in this example uses marshalling techniques so that pointers can be passed between these two threads.

To load and display the filter configuration

  1. In order to read the values stored in the filter vendor parameter set, add the following function to your project:
    HRESULT GetVendorData(FPCLib::IFPCApplicationFilterPtr spiApplicationFilter,
                _bstr_t* pbsVirusString,
                _bstr_t* pbsPrefixString)
{
    HRESULT hr = S_OK;
    FPCLib::IFPCVendorParametersSetsPtr spIFPCVendorParametersSets;
    FPCLib::IFPCVendorParametersSetPtr spIFPCVendorParametersSet;

    try
    {
        spIFPCVendorParametersSet = spiApplicationFilter->VendorParametersSets->Item(_bstr_t(PARAM_SET_GUID));
        *pbsVirusString  = spIFPCVendorParametersSet->Value[_bstr_t("VirusString")];
        *pbsPrefixString = spIFPCVendorParametersSet->Value[_bstr_t("PrefixString")];
;
    }
    catch(_com_error& err)
    {
        return err.Error();
    }

    return S_OK;
}
  2. You need to add code that will call GetVendorData() and display the received data on the property page. Create the OnInitDialog method by using the message-handler wizard. Do this in the same way that you create other message handlers: Use the dialog box itself as the control in the Class or object to handle list and the WM_INITDIALOG message as the event. Add the following code to the generated code (the m_hWnd serves as a handle to the property page; use it when you need to access any of the controls on the property page):
            HRESULT hr;

        _bstr_t bsVirusString, bsPrefixString;
    // Unmarshall an object interface pointer.
    hr =  CoGetInterfaceAndReleaseStream(
                    m_spStreamMarshalApplicationFilter,
                    FPCLib::IID_IFPCApplicationFilter,
                    (void**)&m_spiApplicationFilter);

    // CoGetInterfaceAndReleaseStream releases m_spStreamMarshalApplicationFilter even if it fails.
    // We set it to NULL so that the destructor doesn't try to release this again.
    m_spStreamMarshalApplicationFilter.p = NULL;

    if (FAILED(hr) || !m_spiApplicationFilter.operator bool())
        return hr;

        hr = ::GetVendorData (m_spiApplicationFilter, &bsVirusString, &bsPrefixString);
        if (FAILED (hr))
        {
            bsVirusString  = "Default Virus String";
            bsPrefixString = "Default Prefix String";
        }

        ::SetWindowText (::GetDlgItem (m_hWnd, IDC_VIRUS_STRING),  bsVirusString);
        ::SetWindowText (::GetDlgItem (m_hWnd, IDC_PREFIX_STRING), bsPrefixString);
  3. Add initialization method for the class SmtpFltrSnapInPage:
    //This method is used for passing a pointer to the ApplicationFilter object of the SMTP filter
    HRESULT Initialize(FPCLib::IFPCApplicationFilterPtr DataSource)
    {
        HRESULT hr=S_OK;

        hr = CoMarshalInterThreadInterfaceInStream(FPCLib::IID_IFPCApplicationFilter,
                    (IUnknown *)DataSource,
                    &m_spStreamMarshalApplicationFilter);

        return hr;
    }
  4. Add the two following private members for the class:
    private:
    FPCLib::IFPCApplicationFilterPtr m_spiApplicationFilter;
        // Pointer to stream into which this page's IApplicationFilter object interface
        // pointer will be marshaled.
        CComPtr<IStream>    m_spStreamMarshalApplicationFilter;
  5. Check whether the page was created and initialize the page.
  6. Add the code that is shown in bold font to SmtpFltrSnapIn.cpp.
    HRESULT CSmtpFltrSnapInExtData::CreatePropertyPages(LPPROPERTYSHEETCALLBACK lpProvider,
    long handle,
    IUnknown* pUnk,
    DATA_OBJECT_TYPES type)
{
HRESULT hr;
    // if (type == CCT_SCOPE || type == CCT_RESULT)
    {
        CSmtpFltrSnapInPage* pPage = new CSmtpFltrSnapInPage(handle, true, _T("SmtpFltrSnapIn"));
    if (bstrGUID == _bstr_t("{179A0A70-1EF5-11D3-B160-00A0C9E3F998}"))  // Smtp Filter GUID
        //Check whether the page was created
        if(pPage == NULL)
            return E_UNEXPECTED;
        //Initialize the page.
        if (FAILED(hr=pPage->Initialize(spiApplicationFilter)))
            return hr;
        lpProvider->AddPage(pPage->Create());
        // The second parameter to the property page class constructor
        // should be true for only one page.

        // TODO : Add code here to add additional pages
        return S_OK;
    }
    return E_UNEXPECTED;
}


Saving Configuration Data in the Vendor Parameter Set

Using this procedure, add code to save the filter configuration data in the vendor parameter set.

To save the filter configuration data in the vendor parameter set

  1. Add the following function to store the values in the filter's vendor parameter set:
    HRESULT PutVendorData(FPCLib::IFPCApplicationFilterPtr spiApplicationFilter,
                    const _bstr_t& bsVirusString,
                    const _bstr_t& bsPrefixString,
                    const _bstr_t& bsSMTPIPAddress)
{
    HRESULT hr = S_OK;
    FPCLib::IFPCVendorParametersSetsPtr spIFPCVendorParametersSets;
    FPCLib::IFPCVendorParametersSetPtr spIFPCVendorParametersSet;

    try
    {
        spIFPCVendorParametersSets = spiApplicationFilter->VendorParametersSets;

        try
        {
            spIFPCVendorParametersSet = spIFPCVendorParametersSets->Item(_bstr_t(PARAM_SET_GUID));
        }
        catch(_com_error&)
        {
            //Create a new parameter set
            spIFPCVendorParametersSet = spIFPCVendorParametersSets->Add(_bstr_t(PARAM_SET_GUID),VARIANT_FALSE);

            spIFPCVendorParametersSets->Save();
        }

        spIFPCVendorParametersSet->Value[_bstr_t("VirusString")]   = bsVirusString;
        spIFPCVendorParametersSet->Value[_bstr_t("PrefixString")]  = bsPrefixString;
        spIFPCVendorParametersSet->Value[_bstr_t("SMTPIPAddress")] = bsSMTPIPAddress;
        spIFPCVendorParametersSet->Save();

    }
    catch(_com_error& err)
    {
        return err.Error();
    }

    return S_OK;
}
  2. You need to add a function that will call PutVendorData with the values from ISA Management. To implement this function, override the OnApply method of the CSnapInPropertyPageImpl class. This method is called whenever you click the Apply or OK buttons. Add the following code to your class:
        // This member function is called when the user clicks the OK or the Apply button.
    virtual BOOL OnApply()
    {
        HRESULT hr;
        // _bstr_t bsVirusString, bsPrefixString;
        char sVirusString[100], sPrefixString[100];

        ::GetWindowTextA (::GetDlgItem (m_hWnd, IDC_VIRUS_STRING),
                            reinterpret_cast <char *> (&sVirusString),
                            100);

        ::GetWindowTextA (::GetDlgItem (m_hWnd, IDC_PREFIX_STRING),
                             reinterpret_cast <char *> (&sPrefixString),
                            100);

        hr = ::PutVendorData (m_spiApplicationFilter,
                    _bstr_t(sVirusString),
                    _bstr_t(sPrefixString));

        return TRUE;
    }
  3. Build.


How to Create a Context-Sensitive Menu Extension

The ISA Server Software Development Kit (SDK) includes a sample that extends ISA Management by adding a context sensitive menu. The sample files are in the serversconfigsample directory, under the samples directory in the SDK. The sample adds a menu to the servers node in ISA Management, and by clicking on the node you can see all the adapters for each server in the array.

This section contains the following topics:

  • Building the Context-Sensitive Menu Sample
  • Context-Sensitive Menu Sample Steps
  • Taskpad Extensions
  • Remote Administration Installation


Building the Context-Sensitive Menu Sample

The sample is included in the samples folder of the SDK, in the folder serversconfigsample. To build the sample take the following steps.

To build the context-sensitive menu included in the SDK

  1. Open Microsoft Visual Studio®.
  2. Open the sample workspace, serversconfigsample.dsw.
  3. To see the project files, select the View menu, and then the workspace.
  4. Press the F7 key to build the sample.

This will create the necessary dynamic-link library (DLL). When you register this DLL, you can see the menu when you right click on the servers node in ISA Management and select "view adapters".


Context-Sensitive Menu Sample Steps

To show the context sensitive menu, the sample traverses all the servers in the array, retrieving all the adapters. The information about the adapters on each server is obtained through the administration COM objects. This sample retrieves information about the servers in the array through the IFPCServers and IFPCServer interfaces, and information about the adapters is retrieved through the IFPCAdapter and IFPCAdapters interfaces.

The sample takes the following steps:

  1. Retrieves each server in the array.
  2. Lists all the adapters on each server.
  3. Displays all the adapters.


Retrieving Each Server in the Array

The following code retrieves and stores each server and adapter. This code is taken from the file AdapterList.cpp, included in the serversconfigsample directory.

  1. Create the tree that stores the server and adapter information, shown here:
        /* Make the root of the tree */
    HTREEITEM RootItem = m_ListTree.InsertItem( _T("All Servers"), 0, 0);
    HTREEITEM ServItem;

    /* Make headlines */
    m_ListCtl.InsertColumn( 0, _T("Server Name") );
    m_ListCtl.InsertColumn( 1, _T("Adapter Description") );

    m_ListCtl.SetColumnWidth( 0, LVSCW_AUTOSIZE_USEHEADER );
    m_ListCtl.SetColumnWidth( 1, LVSCW_AUTOSIZE_USEHEADER);
  2. Find each server in the array, shown here:
        /* Go along the hierarchy to find the all the servers */
    /* and their adapters                                 */
    FPCLib::IFPCSnapinNodePtr spiFPCSnapinNode(m_pDataObject);
    FPCLib::IFPCServersPtr spiServers(spiFPCSnapinNode->CurrentObject);


Listing the Adapters

Now that each server has been retrieved, the names of each adapter must be retrieved. This code is taken from the file AdapterList.cpp, included in the serversconfigsample directory.

The code will loop through all the servers in the array, then find all adapters on each server. The names of each are stored, as shown. Each adapter stored in this list will be displayed in the menu.

  1. Find the number of servers in the array. Here the number of servers is being retrieved by using the Count property of the FPCServer administration COM object.
        int Servnum = spiServers->Count;
    int index,index2,LineNumber=0;
    VARIANT ItemNum;
  2. Loop through all servers in the array, and find all adapters on each server. Here is where the code uses the administration objects Adapters and FPCServer to retrieve information about the adapters.
        /* Loop on all the servers */
    for (index=1;index<=Servnum;index++)
    {
        ItemNum.vt = VT_I4;
        ItemNum.lVal =  index;
        FPCLib::IFPCServerPtr spiServer(spiServers->Item(ItemNum));
        _bstr_t name = spiServer->Name;
        FPCLib::IFPCAdaptersPtr spiAdapterList(spiServer->Adapters);

        int AdapNum = spiAdapterList->Count;

        /* Make a node for this server */
        ServItem = m_ListTree.InsertItem( name, 0, 0,RootItem);

        /* Loop on all the adapters */
        for (index2=1;index2<=AdapNum;index2++)
        {
            FPCLib::IFPCAdapterPtr spiAdapter(spiAdapterList->Item(index2));
            _bstr_t Desc = spiAdapter->Description;

            /* Make a line for every adapter */
            m_ListTree.InsertItem( Desc, 0, 0,ServItem);
            m_ListCtl.InsertItem( (LineNumber), _T(""));
            m_ListCtl.SetItemText((LineNumber),0, name );
            m_ListCtl.SetItemText((LineNumber),1, Desc);
            LineNumber++;

        }

    }


Displaying the Adapters

The following code works with the MMC console to show the adapters. This code is taken from the file Adapters.cpp in the sample directory, is written by the Active Template Library (ATL) object wizard and is used at the start of development.

To use the ATL object wizard

  1. Open Microsoft Visual C++.
  2. Click New ATL Object on the Insert menu.
  3. Select MMC Snapin from the Objects list.
  4. Click Next.
  5. Type Adapters in the ShortName box on the Names tab.
  6. Select the Extension and IExtendcontextmenu check boxes on the MMC Snapin tab. (Be sure to leave IComponentData, IComponent, and ISnapInAbout checked.).
  7. Clear the Support Persistence check box.
  8. On the MMC Snapin tab, in the Extends Node box, select the node you want to extend(servers).

The wizard produces the following code.

HRESULT CAdaptersData::Notify( MMC_NOTIFY_TYPE event,
    long arg,
    long param,
    IComponentData* pComponentData,
    IComponent* pComponent,
    DATA_OBJECT_TYPES type)
{
    // Add code to handle the different notifications.
    // Handle MMCN_SHOW and MMCN_EXPAND to enumerate child items.
    // In response to MMCN_SHOW you must enumerate both the scope
    // and result-pane items.
    // For MMCN_EXPAND you only need to enumerate the scope items
    // Use IConsoleNameSpace::InsertItem to insert scope pane items
    // Use IResultData::InsertItem to insert result pane item.
    HRESULT hr = E_NOTIMPL;

    _ASSERTE(pComponentData != NULL || pComponent != NULL);

    CComPtr<IConsole> spConsole;
    CComQIPtr<IHeaderCtrl, &IID_IHeaderCtrl> spHeader;
    if (pComponentData != NULL)
        spConsole = ((CAdapters*)pComponentData)->m_spConsole;
    else
    {
        spConsole = ((CAdaptersComponent*)pComponent)->m_spConsole;
        spHeader = spConsole;
    }

    switch (event)
    {
    case MMCN_SHOW:
        {
            CComQIPtr<IResultData, &IID_IResultData> spResultData(spConsole);
            // TODO : Enumerate the result pane items
            hr = S_OK;
            break;
        }
    case MMCN_EXPAND:
        {
            CComQIPtr<IConsoleNameSpace, &IID_IConsoleNameSpace> spConsoleNameSpace(spConsole);
            // TODO : Enumerate scope pane items
            hr = S_OK;
            break;
        }
    case MMCN_ADD_IMAGES:
        {
            // Add Images
            IImageList* pImageList = (IImageList*) arg;
            hr = E_FAIL;
            // Load bitmaps associated with the scope pane
            // and add them to the image list
            // Loads the default bitmaps generated by the wizard
            // Change as required
            HBITMAP hBitmap16 = LoadBitmap(_Module.GetResourceInstance(), MAKEINTRESOURCE(IDB_ADAPTERS_16));
            if (hBitmap16 != NULL)
            {
                HBITMAP hBitmap32 = LoadBitmap(_Module.GetResourceInstance(), MAKEINTRESOURCE(IDB_ADAPTERS_32));
                if (hBitmap32 != NULL)
                {
                    hr = pImageList->ImageListSetStrip((long*)hBitmap16,
                    (long*)hBitmap32, 0, RGB(0, 128, 128));
                    if (FAILED(hr))
                        ATLTRACE(_T("IImageList::ImageListSetStrip failed\n"));
                }
            }
            break;
        }
    }
    return hr;
}


Taskpad Extensions

You can add tasks to the ISA taskpad. Adding a taskpad task is described in the topic, Using Taskpads, in MSDN.

In the MMC_TASK structure, the nCommandID parameter specifies the command ID returned to the snap-in when the user clicks the task. ISA puts tasks on the taskpad page, in taskpad tabs, or in the task list on the left according to the TaskID you specify. These parts of the taskpad are shown in the following illustration.

To add an extension task use a TaskID in the ranges:

TaskID_RegularRange1Min..TaskID_RegularRange1Max

TaskID_RegularRange2Min..TaskID_RegularRange2Max

TaskID_RegularRange2Min will be <= 0xffff so that standard pointers can be used as TaskIDs.

The following table provides the Task ID ranges:

Task Type | ID Minimum | ID Maximum
Regular (range 1) | 0 | 99
Task tabs | 100 | 299
Task list | 100 | 699
Regular (range 2) | 700 | 0xffffffff

The IExtendTaskPad interface uses the TaskGroup parameter to identify the Taskpad page to be displayed. It returns as the szTaskGroup or pszGroup parameter in the IExtendTaskPad methods: EnumTasks, GetBackground, GetTitle, GetDescriptiveText, and GetListPadInfo.

The following table provides the TaskGroup strings that are returned for the taskpad pages of ISA.

Description | String
Main taskpad page for the node | IsaTaskGroup_MAIN
Main internal (publishing) taskpad page for the node | IsaTaskGroup_MAIN_INTERNAL
Main external taskpad page for the node | IsaTaskGroup_MAIN_EXTERNAL
Main monitoring taskpad page for the node | IsaTaskGroup_MONITORING
Main backup taskpad page for the node | IsaTaskGroup_BACKUP

Note All Getting Started nodes should begin with "GS_" (defined by TP_GETTING_STARTED), to differentiate them from main pages.


Remote Administration Installation

A user may choose to install only the administration components of ISA Server on a particular computer, thereby creating a remote administration computer for ISA Server. That computer will provide the administrator with ISA Management, but will not include ISA engine components.

If your filter includes user interface elements, you should provide an administration component installation option. The administrator will then be able to install only the administrator's user interface for your filter to the administration computer, and install the filter itself to ISA Server computers.

If you create scripts that will run on a remote administration computer, you should create the root object by using the FPCDS object, rather than the FPC object. For more information, see FPC Object and Creating the Root ISA Object.


Developing Application Filters

This section describes the basic steps required to create an application filter. This section is intended for developers who are familiar with Microsoft® Visual C++® and COM. For performance reasons, application filter interfaces are not automation interfaces and filter objects are best implemented as free-threaded objects. Therefore, Visual Basic, Java and scripting languages are not suitable for creating application filters.

Because application filters work with the Firewall service, and the Firewall service works with Windows Sockets (Winsock), knowledge of Winsock is also helpful. Information about Winsock can be found in MSDN.

To become familiar with the filter-development process, the following approach is recommended:

  1. Read the description of Internet Security and Acceleration (ISA) architecture in About Internet Security and Acceleration Server.
  2. Read Introducing Application Filters for information on the basics of filter functionality.
  3. Study Filter Development Tools, particularly the general descriptions of the basic and advanced object interfaces needed for filter creation.
  4. Work through the step-by-step procedure provided in How to Create an Application Filter.
  5. Examine the logic and interface usage of the sample filters provided with ISA.
  6. Develop a simple filter. See the Reference for details on interface methods and parameters.

Topics in this Section

This section contains the following topics:

  • Introducing Application Filters
  • Filter Development
  • Application Filter Test Environment
  • Filter Setup
  • How to Create an Application Filter
  • Sample Filters


Introducing Application Filters

Application filters work with the Firewall service to intercept and process data. Application filters can access the data stream or datagrams associated with a session within the Firewall service. The filters are registered with the Firewall service and act according to events detected by the service. An application filter can perform protocol-specific or system-specific tasks, such as authentication and checking for viruses.

This section contains the following topics, which are best read in sequence:

  1. Filter Types
  2. Firewall Events
  3. Connection Emulation
  4. Checking Access Rights
  5. Asynchronous Input/Output
  6. Filter Requirements for SecureNAT Clients
  7. Filter Requirements for Firewall Clients
  8. Setting Filter Priorities
  9. Application Filter Objects
  10. Filter Object Model
  11. Filter Alert Events


Filter Types

You can develop a wide range of application filters by using the ISA Server Software Development Kit (SDK). Examples of filter types are:

  1. Protocol-enabling filters: These filters enable the usage of a protocol through the Firewall service. These filters open dynamic secondary ports, and edit Secure Network Address Translation (SecureNAT) addresses. The FTP and H.323 filters provided with ISA Server are examples of protocol-enabling filters.
  2. Protocol-scanning filters: These filters scan data from specific protocols for intrusion, viruses, and so on. Examples of protocol-scanning filters are the Internet Security Systems (ISS) POP and DNS filters that are provided with ISA Server.
  3. Redirection filters: These filters may cause specific connections to be redirected into their control and act as a server. For example: The HTTP redirector filter provided with ISA Server redirects HTTP connections to the Web Proxy service.
  4. Other filters, such as those that check content. ISA Server's architecture allows developers a great deal of latitude in creating filters.


Firewall Events

Firewall events are events that the Firewall service detects. An application filter has to be registered for specific events. If that event is detected by the Firewall service, the filter is attached to the related session. The filter can then monitor the session for events where a filter response, such as data filtering, might be needed.

In general, the events are generated both in the case of Firewall clients and SecureNAT clients. For more information and a list of events, see FwxFirewallEventType.


Connection Emulation

You can design a filter that intercepts a client request to connect to the Internet, and instead provide the information from another source. In this case, you are emulating an outside connection, and the client is unaware that the data is coming from a source other than the requested external one. An HTTP filter that provides a Web object from a cache is emulating a connection.

An inbound connection can also be emulated. For example, a filter can emulate a connection on a single well-known port, so that a number of client machines can effectively use the connection simultaneously. This emulation scenario is demonstrated in the ServerSplit sample.


Checking Access Rights

When a client requests an external connection, the Firewall service determines if the client is allowed to access the connection. The Firewall service checks:

  • Which protocol the connection will use.
  • Whether the client has the right to make a connection by using that protocol.

The Firewall service can determine which protocol the connection will use, based on a protocol schema it can reference. This schema, provided to the Firewall service as a feature of ISA, recognizes a defined set of protocols. The Firewall service also uses the protocol-recognition capabilities of application filters in the identification process. The advantage of filter control of protocol recognition is that a filter can recognize which protocol is associated with a secondary connection, whereas the Firewall service cannot.

The Firewall service takes two sequential steps to determine whether a client is allowed access to the connection. If the connection is denied at any point in the process, the service stops the checking procedure and denies the connection. The two steps are:

  1. Checking site and content rules.
  2. Checking protocol rules. Checking protocol rules takes place in three sequential phases:
    1. Checking against the protocol schema.
    2. Checking whether the IFWXSession::AllowFutureConnect method has been set.
    3. Checking whether the IFWXConnection::SetProtocol method is called by a filter.

Checking Site and Content Rules

When the Firewall service checks site and content rules, the connection will be denied if the rules do not permit the client to connect to that destination. If the rules allow the client to make that connection, the service passes along the request to the second step — checking protocol rules. At this point, the permission is "unset", because the service is not authorized to allow the connection based solely on the site and content rules.

For more information about site and content rules, see the FPCSiteAndContentRule object or the ISA product documentation.

Checking Protocol Rules

After checking the site and content rules, the Firewall service checks the protocol rules configured by the administrator. These rules allow or deny connection requests based on the protocol. If not explicitly denied, the connection request is passed to the registered filters for their review.

When the Firewall service checks protocol rules it starts by referring to the protocol schema in order to recognize the protocol for the requested connection.

After checking protocol rules by using the schema, the service checks whether any filters have called IFWXSession::AllowFutureConnect.

If the AllowFutureConnect method has been called, the filter has already checked the connection against the protocol rules. Based on the protocol rules, the filter has associated the connection with the protocol and has informed the Firewall service of the association. This information is used by the service in this step of checking access rights.

If AllowFutureConnect has not been called, the Firewall service checks whether SetProtocol is called by a filter. If so, the filter has identified a protocol, and if allowed by the protocol rules, SetProtocol associates a connection with that protocol.

Note SetProtocol associates a connection with a protocol in response to an event, whereas AllowFutureConnect creates that association in anticipation of the event.

If a filter allows the connection, the connection request is passed to the next registered filter. If each filter allows the connection, or does not relate to the connection request, the connection is allowed. If any filter relates to the request and denies it, the connection is denied.


Asynchronous Input/Output

ISA uses asynchronous input/output (I/O) to manage multiple I/O requests simultaneously. This results in more efficient use of resources because the Firewall service can continue I/O while waiting for particular data.

The asynchronous I/O operation takes the following steps:

  1. The data buffer object is created by the Firewall service.
  2. Data is received asynchronously.
  3. The data transfer is completed.
  4. The Firewall service receives the completion notification through the completion port, and passes it to the completion object.
  5. The completion method information is received by a Completion Notification object.

For this process to take place, the application filter follows these steps:

  1. Calls an asynchronous method to issue an overlapped request.
  2. Waits for the request to be handled asynchronously and completed.
  3. Receives notification through a completion notification interface.

    Note This process differs for Win32 overlapped operations. For more information see IFWXExternalIOCompletion.

The following objects are directly related to ISA Server's implementation of asynchronous input/output:

  • Buffer objects that implement the IFWXIOBuffer interface.
  • Overlapped objects that implement the IFWXOverlapped interface.
  • Completion notification objects that implement the IFWXAcceptCompletion, IFWXIOCompletion, or IFWXExternalIOCompletion interface.


Filter Requirements for SecureNAT Clients

Application filters can work with Firewall clients and SecureNAT clients. This section describes specific design considerations for filters that must work with SecureNAT clients. For information on designing filters to work with Firewall clients, see Filter Requirements for Firewall Clients.

To handle SecureNAT client connect requests for outbound primary connections, the filter must register for events originating from a SecureNAT client. Use the fwxSourceNAT value of the FwxFirewallEventSource enumerated type when registering for SecureNAT client events. To handle both Firewall client and SecureNAT client requests, use the macro FWX_ALL_SOURCES.

If a filter is going to handle inbound connections to SecureNAT clients, including primary connections, a specific protocol has to be registered and associated with the Connection object. Use IFWXFilterAdmin::RegisterProtocolForFilter to register the protocol, and IFWXConnection::SetProtocol to associate the protocol with the Connection object.

Inbound primary connections can be directed to the SecureNAT client by using the IFWXFirewall::CreatePrivateSession or IFWXFirewall::GetNATSession method. Use IFWXFirewall::CreatePrivateSession when the inbound connection has been requested by an application, the SecureNAT client is not known by the Firewall service, and no session object has been created. Use IFWXFirewall::GetNATSession only if the filter can assert that the client is configured to be a SecureNAT client of that server.

Use the IFWXSession::BindForClient method to permit SecureNAT clients to receive secondary inbound connections. Data filters that call IFWXSession::BindForClient and then edit addresses passed on a connection should use the fwx_dfpc_NAT value of the FwxDataFilterPriorityClass enumerated type. This places the filter as close to the client as possible, that is, it is the first data filter to receive data from the client. This is important because you want to ensure that the first filter to handle the SecureNAT data is one that is capable of doing so. For more information, see Setting Filter Priorities.

Note In a publishing scenario, mapping of the internal, SecureNAT addresses for your publishing server to external IP addresses is done by using ISA Management or the FPCServerPublishingRule object.


Filter Requirements for Firewall Clients

Application filters can work with both Firewall clients and SecureNAT clients. This section describes specific design considerations for filters that must work with Firewall clients. For information on designing filters to work with SecureNAT clients, see Filter Requirements for SecureNAT Clients.

To handle Firewall client connect requests for outgoing primary connections, the filter must register for events originating from a Firewall client. Use the fwxSourceWSP value of the FwxFirewallEventSource enumerated type to register for Firewall client events. A filter designed to handle both Firewall client and SecureNAT client requests should use the macro FWX_ALL_SOURCES to include both values.

To allow a Firewall client to receive a secondary inbound connection, use IFWXSession::RetroactiveAllowBind. Use this method because the client application may have already bound a socket on the Firewall service, and the filter should use that socket. IFWXSession::RetroactiveAllowBind enables the previously created bind by associating it with a protocol, and also tests to see if the client application bound a Firewall service socket. If the client application did not bind a Firewall service socket, IFWXSession::RetroactiveAllowBind will fail. Therefore, the filter should also call IFWXSession::BindForClient. IFWXSession::BindForClient lets a client application — for which the Firewall client component failed to create a remote socket for a bind call — receive an inbound connection.


Setting Filter Priorities

Typically, more than one data filter will be registered for the same event. The order in which data filters react to events can affect the results.

The priority coded into the data filter determines the order in which filters access data. The possible priority settings are defined in the enumerated type FwxDataFilterPriorityClass. Each priority setting is defined as being closer to the client or closer to the server. A data filter that is closer to the client is likely to be the first to examine data flowing from the client, but least likely to be the first to examine data flowing to the client. A data filter that is closer to the server is likely to be the first to examine data flowing from the server to the client, and unlikely to be the first to examine data flowing from the client to the server.

Data filter priority is important because the first data filter in a chain of data filters can affect the data received by subsequent filters.

When two or more data filters share the same priority, the order in which they address the data is arbitrary.


Application Filter Objects

Before developing application filters, it is useful to understand the basic objects related to filter function. These are:

  • Socket objects
  • Connection objects
  • Session objects
  • Filter objects
  • Session filter objects
  • Data filter objects
  • Buffer objects
  • Completion Notification objects

    Note The ISA application filter objects use a free-threaded threading model.


Socket Objects

A "socket" is an endpoint of communication — an object through which your application communicates with other Windows Sockets (Winsock) applications across a network. There are sockets on the client and server sides.

The steps used on the client side for communication through sockets are:

  1. Open: The networking application creates a socket for a specific protocol.
  2. Bind: The socket is assigned a name (address). In TCP/IP, the application assigns a port, and may also assign an IP address if the computer is multihomed.
  3. Connect: A connection is established with the server socket, so that send and receive operations can take place. You can connect a socket for which there has been no bind, and the bind will take place as part of the connect. An explicit bind is needed only if a specific port and IP address are needed for the connection.

The steps used on the server side for communication through sockets are:

  1. Open: Create the socket.
  2. Bind: The bind is usually performed on a well-known port.
  3. Listen: Be prepared to accept connections. The listen operation takes place on the kernel level.
  4. Accept: Accept the connection and open a new socket for it. This socket is passed to the application so that it can communicate with the client. The listening socket continues to listen for additional connect requests, so that other accept functions can take place.

For more information on sockets, see MSDN. See Socket Implementation in ISA for specifics about using sockets with this product.


Socket Implementation in ISA

Each data filter works with two objects that implement a socket interface. One represents the internal socket and the other represents the external socket, and the filter pumps data between them.

ISA has two interfaces through which you can manage socket activity:

  • IFWXSocket
  • IFWXNetworkSocket

IFWXSocket

IFWXSocket is the interface for a socket that was opened by the Firewall service. The IFWXSocket interface has limited functionality; its methods allow you to send and receive on the socket, or to close the socket.

The limited functionality of IFWXSocket is intentional: A data filter that uses two IFWXSocket interfaces to send and receive data does not know whether it is communicating with the Internet, the client, or another data filter in a chain of data filters.

Because IFWXSocket is for use only with existing sockets, there is no allowance for functions such as bind or connect.

IFWXNetworkSocket

The IFWXNetworkSocket interface is an extension of the IFWXSocket interface. IFWXNetworkSocket represents a true socket object for either the client or server. It allows you to establish a socket, then use the IFWXSocket functionality to perform send and receive operations. Therefore, in addition to the send, receive, and close functions of IFWXSocket, IFWXNetworkSocket provides methods such as Bind, Connect, and Listen.

The socket object for IFWXNetworkSocket can be created by using either IFWXFirewall::CreateNetworkSocket or IFWXSession::CreateNetworkSocket. In either case, the socket object created by using CreateNetworkSocket has full socket functionality for operations such as opening a packet filter or working with chained ISA Server computers.

A socket created by using IFWXFirewall::CreateNetworkSocket is not user specific. An example of a socket that should not be user-specific is a listening socket.

To create a user-specific socket, use IFWXSession::CreateNetworkSocket. The socket created by IFWXSession::CreateNetworkSocket has the same functionality as that created by IFWXFirewall::CreateNetworkSocket, but because it is user specific, its activities can be logged, and ISA's policies apply to it. The use of this kind of socket is appropriate when a filter will be making a connection for a specific user.

Warning

There are three reasons to create Windows Sockets (Winsock) for ISA only through the CreateNetworkSocket method:

  • The application filters and the Firewall service should use the same thread pool, and thus the same completion port.
  • With IFWXNetworkSocket, the filter becomes part of the dynamic packet filtering scheme. A socket created by using Firewall service interfaces would not be able to connect to an external address when packet filtering is enabled.
  • Proxy chaining is supported only by IFWXNetworkSocket.


Connection Objects

Connection objects provide a means for the Firewall service to perform services for a client socket. For those specific services, such as setting up a remote socket for a client socket, the connection object represents the client socket to the Firewall service. When a Firewall client uses bind, connect, or sendto Winsock functions, and the client DLL identifies a remote destination, the Firewall service creates a connection object that resides on the server.

Similarly, a connection object will be generated for a SecureNAT client. In the case of the SecureNAT client, the Firewall service first receives the request from the client, identifies it as originating from a SecureNAT client, and then creates the connection object and proceeds.

Connection objects are also created when BindForClient is called. In this case, an application filter, rather than the Firewall service, identifies that the client called bind.

Connection objects implement the IFWXConnection interface. For examples of how the Firewall service uses the IFWXConnection interface, see IFWXConnection in Basic Filter Interfaces.


Session Objects

A session is a group of connections that are related because they are associated with a particular client. For Firewall clients, a session is created for each control channel. For SecureNAT clients, a session is created for each client IP address.

The Firewall service creates a session object for each session. The session object can be used to query about the user that made the connection and the user's permissions, for modifying the permissions of future connections, and for performing network operations on behalf of the application. The session object provides specific functionality through the IFWXSession interface, including the following:

  • Retrieving the name or address of the user's computer.
  • Allowing inbound connections for an existing bind.
  • Creating a bind on behalf of a client.
  • Impersonating the user's account.
  • Querying the Firewall service about a user's access rights.
  • Creating a user-specific socket for a client.


Filter Objects

Each application filter is represented by a filter object called FWXFilter. The FWXFilter object implements the IFWXFilter interface, used by the Firewall service to load and initialize the application filter and to create session filters.


Session Filter Objects

A session filter is created and attached to a session when the Firewall service detects an event for which the application filter has registered. By being attached to the session, the session filter can receive notification events and react to them. For example, a session filter could react to a notification event by placing a data filter on the session data.

Each session filter is represented by an FWXSessionFilter object implementing the IFWXSessionFilter interface.


Data Filter Objects

A session filter may, in response to an event, ask the Firewall service to create a data filter. The data filter is provided with an internal and external socket, and functions as a data pump between the two sockets. The data filter is represented by an object that implements the IFWXDataFilter interface.


Buffer Objects

ISA handles data in data buffers. Each data buffer is represented by a buffer object. By using pointers to the buffer object, various components, such as a series of filters can use the same data without the need to copy data. Avoiding copying data improves performance.

A buffer's size is defined in two ways:

  • Allocated size
  • Actual size

The allocated size is the buffer's capacity in bytes and does not reflect data actually stored in the buffer. When a buffer is created and filled by a filter, it begins with a defined allocated size. The actual size is the number of bytes of data the buffer currently holds.

A filter can perform the following buffer management activities:

  • Read into a buffer directly from a memory pointer by using the IFWXIOBuffer::Append method.
  • Read a buffer by using the IFWXIOBuffer::GetBufferAndSize method.
  • Read a portion of a buffer by using the IFWXIOBuffer::ReadAt method.
  • Send data from a buffer to another buffer by using the IFWXIOBuffer::SendToBuffer method.
  • Manipulate the memory directly by using the IFWXIOBuffer::GetBufferAndSize method. This operation can only be performed by the buffer owner (the filter that created the buffer).
  • Reset the buffer size by using IFWXIOBuffer::SetDataSize method.

For more information about these methods, see IFWXIOBuffer.

Buffer objects implement the IFWXIOBuffer interface.

Using the IFWXIOBuffer interface, information about the buffer can be retrieved and the buffer can be modified. For examples of how the Firewall service uses the IFWXIOBuffer interface, see Basic Filter Interfaces.


Completion Notification Objects

Completion notification objects work with Completion Port objects, also known as I/O Completion Port objects, to allow the operating system to handle multiple threads efficiently for asynchronous I/O. For more information on use of completion ports in Windows, see MSDN. The firewall service completion port is a completion port requested by the Firewall service from Windows 2000 that remains associated with the service. The completion port is associated with a number of client connections. All I/O operations should make use of the firewall service completion port so that I/O operations take place efficiently.

To use a completion port you need to provide an I/O Completion Notification object that will receive notification when the I/O operation has completed. Hook the handle to the firewall service completion port by using the IFWXFirewall::HookToCompletionPort method. The firewall service provides the Overlapped object, completion port de-queuing, and the thread pool. To receive notification that the I/O has been completed, use the IFWXOverlapped::SetNotificationInterface method.

Asynchronous I/O and Completion Ports

When an asynchronous I/O operation has been completed on a particular connection, the Firewall service notifies the completion port by using one of three completion notification methods:

  • IFWXIOCompletion::CompleteAsyncIO
  • IFWXAcceptCompletion::CompleteAsyncAccept
  • IFWXExternalIOCompletion::CompleteAsyncIO

Each of these methods includes a Boolean succeed/fail parameter, a Win32® error code parameter, and a user-data parameter that provides user-context information. However, the method used by the firewall service to send the notification depends on the type of I/O operation that has been completed.

IFWXIOCompletion::CompleteAsyncIO

This is the general method for receiving notification from the Firewall service when an asynchronous I/O operation is completed. When a data buffer has been completed through an asynchronous I/O operation, the notification is sent to IFWXIOCompletion::CompleteAsyncIO.

IFWXAcceptCompletion::CompleteAsyncAccept

This method receives notifications from the Firewall service when an IFWXNetworkSocket:Accept is completed on a listening socket.


IFWXExternalIOCompletion::CompleteAsyncIO

IFWXExternalIOCompletion::CompleteAsyncIO is the I/O completion notification used with asynchronous I/O for operating system files. If the Firewall service has a handle for an operating system file, and needs to call the file or write to it, this operation will be asynchronous, so that it can take place in the background. An example of an asynchronous I/O operation for operating system files is writing to or reading from a disk.

There are four sequential steps to this process:

  1. The Firewall service calls IFWXFirewall::HookToCompletionPort, which connects the file handle to the service's completion port. This step takes place once per connection.
  2. The Firewall service calls IFWXFirewall::CreateOverlapped to create the Overlapped object, which implements the IFWXOverlapped interface.
  3. The Firewall service uses IFWXOverlapped::GetOverlapped to get a pointer to the Winsock OVERLAPPED structure, and IFWXOverlapped::SetNotificationInterface to send notification when the I/O operation has been completed.
  4. IFWXExternalIOCompletion::CompleteAsyncIO receives the notification, including a succeed or fail message, information regarding the user, and the number of bytes transferred.

The following figure summarizes the process of asynchronous I/O for operating system files.


Filter Object Model

When the Firewall service starts, it implements the IFWXFirewall interface.

The Firewall service creates application filter instances. Each application filter implements the IFWXFilter interface. The Firewall service initializes the application filter by using the IFWXFilter::FilterInit.

The application filter registers for events. When the Firewall service detects an event for which the application filter is registered, it uses IFWXFilter::AttachToSession to inform the application filter that the event has occurred. The application filter then creates an instance of the session filter, which implements IFWXSessionFilter.

The session filter object refers to the session object, represented by the IFWXSession interface, for client and user information.

When an event is detected that the filter is interested in, as indicated in the output of IFWXFilter::AttachToSession, the Firewall service notifies the filter by calling the IFWXSessionFilter::FirewallEventHandler method.

When it is notified by the Firewall service that an event the filter is interested in has occurred, the session filter can create an instance of a data filter, which implements the interface IFWXDataFilter. Alternatively, data filters can be created by using IFWXSession::SetDataFilterFactory. The session filter object attaches the data filter to the connection related to the specific event. The connection implements the IFWXConnection interface.

IFWXConnection provides the data filter with the internal and external sockets by using IFWXDataFilter::SetSockets. Each socket object implements the IFWXSocket interface. The data filter then performs the data pumping and filtering for a specific connection.

Data is received as buffers. To avoid the need to copy buffers, each buffer is handled as an object, FWXIOBuffer, that implements the IFWXIOBuffer interface. Since data is received asynchronously, the data filter must implement IFWXIOCompletion, which is necessary for asynchronous input/output (I/O) on the sockets. When an asynchronous I/O operation is completed, the Firewall service uses IFWXIOCompletion::CompleteAsyncIO to notify the data filter that the buffer is available to it.

The data filter can then perform its filtering function on the data buffer.

Filter registration procedures are described in Filter Setup.

The phases of a filter's operation are shown in the following figure. See ConnectorFilter for a diagram that illustrates the logic of a specific filter.


Filter Alert Events

When you create an application filter, you may want it to register an alert event that the ISA administrator can use to raise an alert. For example, if your filter looks for a particular string in e-mail, you may want to make it possible for an administrator to be notified when that string is found.

For information on alerts, see Adding a Custom Event and Alert.

The steps you need to take in the code of your filter are as follows:

  1. Register alert events in ISA.

    The filter must define an alert event, which it will signal whenever the event (not to be confused with a firewall event) occurs.

    Definition of the alert event should take place during registration of the filter with the Firewall service because you want the administrator to be able to define alerts by using this event. When the filter is unregistered, it should remove this event definition.

  2. Create an alert that uses the event.

    Creation of an alert is described in the ISA product documentation.

  3. Signal event when the string is found.

    To raise an event, the filter must use the alert service API.

  4. Call the IFPCAlertNotification::SignalEvent method to signal when the event occurs.

An example of this procedure is provided in the topic Raising an Event When a String is Found. The procedure is also used in the SMTP filter sample (SMTPFLTR) provided with the ISA Server SDK.

Note Uninstalling a filter should remove the events that were defined during filter installation, and any related alerts.


Filter Development

This section describes the tools provided by ISA to develop application filters and the application filter development process. This section contains the following topics:

  • Filter Development Tools
  • Filter Development Process
  • Best Practices


Filter Development Tools

ISA provides the tools you need to develop application filters. This section describes those tools.

This section contains the following topics:

  • Header and .Idl Files Provided with ISA
  • Application Filter Interfaces


Header and .Idl Files Provided with ISA

The ISA SDK provides you with the .h and .idl files needed to create a filter. You need to include the appropriate SDK files in your project. For an example of how to do this, see the procedure in How to Create an Application Filter.

The SDK files include:

  • wspfwext.idl
  • wspfwtyp.h
  • wspfwerr.h
  • msfpccom.idl
  • fpcimports.h
  • fpcimports.idl

Of these, wspfwext.idl and msfpccom.idl are of the greatest interest to filter developers.

wspfwext.idl

Contains the definitions and globally unique identifiers (GUIDs) of the object interfaces. When you first compile your project, the files wspfwext.h and wspfwext_i.c are generated from wspfwext.idl.

wspfwtyp.h

Defines Windows and Winsock structures for the Microsoft Interface Definition Language (MIDL) compiler, which compiles the .idl files.

wspfwerr.h

Contains error code definitions for the Firewall service.

msfpccom.idl

Contains the definitions of the ISA administration COM objects.

This file will generate the msfpccom.tlb file. In order to be able to use properties and methods that return enumerated-type values without explicitly specifying the namespace, specify no-namespace when you import the msfpccom.tlb file, as follows:

#Import "msfpccom.tlb" no_namespace

fpcimports.h

Allows inclusion of standard system header files in an .idl file. Works with fpcimports.idl. For more information, see the section on importing system header files in MSDN.

fpcimports.idl

Allows inclusion of standard system header files in an .idl file. Works with fpcimports.h. For more information, see the section on importing system header files in MSDN.


Application Filter Interfaces

There are 20 interfaces defined in the wspfwext.idl file. Of these, the filter implements eight interfaces, the Firewall service implements 11, and one interface can be implemented by either the service or the filter. See the Reference section for detailed descriptions of interfaces.

This section contains the following topics:

  • Basic Filter Interfaces
  • Advanced Filter Interfaces


Basic Filter Interfaces

Basic filter development will require that you work primarily with the following interfaces:

Interface | Implementation
IFWXFilter | Implemented by the application filter.
IFWXSessionFilter | Implemented by the application filter.
IFWXDataFilter | Implemented by the application filter.
IFWXIOCompletion | Implemented by the application filter.
IFWXConnection | Implemented by the firewall service.
IFWXUdpDestination | Implemented by the firewall service.
IFWXSocket | Implemented by the firewall service.
IFWXIOBuffer | Generally implemented by the firewall service.
IFWXFirewall | Implemented by the firewall service.
IFWXSession | Implemented by the firewall service.
IFWXFilterAdmin | Implemented by the firewall service.

These interfaces are introduced in this section. They are described in the order in which they typically might be used in code.


IFWXFilter

The Firewall service uses the IFWXFilter interface to load and initialize a filter and to create session filters. An IFWXFilter interface is called for each filter that is in ISA storage and is enabled.

Notes to Implementers

IFWXFilter is the first interface that you need to implement.

In IFWXFilter you define a port, or range of ports, to be monitored, and the events that will trigger a call to the IFWXFilter::AttachToSession method.

Note There are situations where threading issues require caution in the implementation of IFWXFilter::FilterShutdown. For more information, see the Reference section.

ISA Samples that Use IFWXFilter Methods

The methods IFWXFilter::FilterInit, IFWXFilter::FilterShutdown, and IFWXFilter::AttachToSession are used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

Example Code

Following are examples of code to implement IFWXFilter methods:

IFWXFilter::FilterInit

HRESULT STDMETHODCALLTYPE
CMyFWXFilter::FilterInit(
IFWXFirewall         * pFirewallInterface,
FwxFilterHookEvents ** ppFilterHookEvents)
{
    //Listening on port <range>
        m_FwxPortRangeEvents.StartPort=<start range>;
        m_FwxPortRangeEvents.EndPort=<end range>;

    //Initialize events
        m_FwxPortRangeEvents.dwSocketEvents=<FwxFirewallEventSource>
                        | <FwxFirewallEventType>;
        m_FwxFilterHookEvents.dwGlobalEvents=<FwxFirewallEventSource>
                        | <FwxFirewallEventType>;
        m_FwxFilterHookEvents.dwNumPortRanges = <No. of entries in     FwxPortRangeEvents>;
        m_FwxFilterHookEvents.FwxPortRangeEvents = &m_FwxPortRangeEvents;

    m_spFirewall = pFirewallInterface;
    return m_spFirewall->DuplicateFilterHookEvents(
    &g_MyHookEvents,
    ppFilterHookEvents);
}

IFWXFilter::AttachToSession

HRESULT STDMETHODCALLTYPE AttachToSession(
    /* [in] */ IFWXSession __RPC_FAR *piSession,
    /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
    /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
{
CComObject<CMyFWXSessionFilter> *pMySessionFltr;
CComObject<CMyFWXSessionFilter>::CreateInstance(
                        &pMySessionFltr);
// Other initializations here.

pMySessionFltr->QueryInterface(
                        IID_IFWXSessionFilter,
                        ppISessionFilter);

m_spFirewall->DuplicateFilterHookEvents(
                        &g_MySecondaryHookEvents,
                        ppFilterHookEvents);
}


IFWXSessionFilter

The filter implements the IFWXSessionFilter interface to monitor and react to events in a given session.

Notes to Implementers

This is the second interface for which you need to write code, and which must be implemented by each application filter. This is the interface typically used for attaching a data filter to a session.

The interface is implemented on each session filter object. A different combination of session filters can be attached to each user session. However, a session filter is usually attached to a single user session.

Remarks

In the IFWXSessionFilter::FwxFirewallEventHandler method select an action based on the event data provided by the Firewall service.

In IFWXSessionFilter::Detach you would typically release references to other objects.

ISA Samples that Use IFWXSessionFilter Methods

The method IFWXSessionFilter::FwxFirewallEventHandler is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSessionFilter::Detach is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • SMTPFLTR

Example Code

Following are examples of code to implement IFWXSessionFilter methods.

IFWXSessionFilter::FwxFirewallEventHandler

HRESULT
CMyFWXSessionFilter::FwxFirewallEventHandler(
                    FirewallEvent *pEvent)
{
    switch (pEvent->EventType) {
    case fwx_Connect_Tcp:
        // Handle connect event
    case fwx_Accept:
        // Handle accept event
…
}

IFWXSessionFilter::Detach

    HRESULT
    CMyFWXSessionFilter::Detach()
{
    // Assuming that m_spSession is defined
    // as CComPtr<IFWXSession>, IFWXSession::Release() is called
    // by the assignment operator.
    Lock();
    m_spSession = NULL;
    Unlock();

    return S_OK;
}


IFWXDataFilter

IFWXDataFilter is the interface for a data filter. The data filter functions as the Firewall service's data pump and performs the data filtering.

Notes to Implementers

Filters that examine data require a data pump to pass data through the connection.

There are two approaches to creating data filter instances:

  1. Implement IFWXConnection::AttachDataFilter to create and attach a data filter by adding code to the session filter. The session filter will then attach a data filter instance to the connection whenever the registered event occurs.
  2. Provide an object that implements the standard COM IClassFactory interface. An example of this approach is provided in How to Create an Application Filter.

Remarks

Implement the IFWXConnection interface methods (implemented by the Firewall service) to attach the data pump, and IFWXSessionFilter::FwxFirewallEventHandler to receive information about the event. Through the IFWXDataFilter::SetSockets method, the Firewall service provides socket interfaces to the data filter for the sockets on the internal and external computers. The Firewall service calls the IFWXDataFilter::Detach method when the connection to the sockets is no longer needed. When IFWXDataFilter::Detach is called you must code a release to the sockets so that the system can delete the socket objects.

The Firewall calls IFWXIOCompletion::CompleteAsyncIO when the I/O operation is completed. The data filter object inherits the CompleteAsyncIO method from IFWXIOCompletion. The data is then available for the data pump and filter.

Handling Data Received from Another Protocol

When the primary port of a protocol lies within the dynamic port range (1024 – 5000), a filter for that protocol will receive a firewall event if that port is selected for another protocol's secondary connection. However, when the data stream through that secondary connection does not comply with the filter's expected protocol, the filter must be able to handle this situation gracefully.

The proper approach is to design a filter to revert to a simple data pump if the data stream is not the expected protocol. Note that it is possible in this way for data that would have been rejected at the primary port to pass through the filter at the secondary port.

ISA Samples that Use IFWXDataFilter Methods

The method IFWXDataFilter::SetSockets is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXDataFilter::Detach is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • SMTPFLTR

Example Code

Standard Declaration of Data Filter Object

//Note that IFWXIOCompletion::CompleteAsyncIO is made
//public in this declaration, and must be implemented
//by this object.
class ATL_NO_VTABLE CDumpData :
    public CComObjectRootEx<CComMultiThreadModel>,
    public IFWXDataFilter,
    public IFWXIOCompletion
{

IFWXDataFilter::SetSockets

STDMETHODIMP
//DumpData is the name of object that implements
//IFWXFilter in this example
CDumpData::SetSockets(
    IN   IFWXSocket *piInternalSocket,
    IN   IFWXSocket *piExternalSocket,
    IN   IFWXConnection *piConnection,
    IN   IUnknown *punkFilterContext
    )
{
    // Using Lock/Unlock, all access to the sockets is protected
    // because Detach could be called at any time.
    Lock();
    m_spInternalSocket = piInternalSocket;
    m_spExternalSocket = piExternalSocket;
    Unlock();
    //ReadFirstBuffer is a function that waits for
    //data on both sockets.
    return ReadFirstBuffers();
}

The variables m_spInternalSocket and m_spExternalSocket are defined as follows:

    CComPtr<IFWXSocket>    spExternalSocket = m_spExternalSocket;
    CComPtr<IFWXSocket>    spInternalSocket = m_spInternalSocket;

Simple Implementation of CompleteAsyncIO

STDMETHODIMP
//DumpData is the name of object in this example
CDumpData::CompleteAsyncIO(
    IN BOOL      fSuccess,
    IN DWORD     Win32ErrorCode,
    IN IFWXIOBuffer *pIOBuffer,
    IN DWORD     dwUserData,
    IN PSOCKADDR From,
    IN INT       FromLen
    )
{
    DWORD NumberOfBytesTransfered = 0;
    PBYTE pbBuffer;
    BOOL  fShutdown;
    char *pszReadSource;
    IFWXSocket *piSocket;

    // Set the target socket for the buffer.
    if (dwUserData == ReadFromInternal) {
        piSocket   = GetExternalSocket();
        pszReadSource = "Internal";
    } else {
        piSocket = GetInternalSocket();
        pszReadSource = "External";
    }

    if (fSuccess && pIOBuffer) {
        pIOBuffer->GetBufferAndSize(&pbBuffer,
                                &NumberOfBytesTransfered);

    if (piSocket == NULL) {
        return S_OK;                    // Detach was called
    }
//This particular filter just receives and sends the data.
//This is the point in the code where a filter's functionality
//should be inserted.
    // Send the buffer
    if (!fSuccess || NumberOfBytesTransfered == 0) {
        fShutdown = TRUE;
        piSocket->Shutdown(!fSuccess);
    }
        else {
        fShutdown = FALSE;
        if (From == NULL) {
            piSocket->Send(pIOBuffer, NULL, 0);
        } else {
            piSocket->SendTo(pIOBuffer, From, FromLen, NULL, 0);
        }
    }

    piSocket->Release();

    if (fShutdown) {
        return S_OK;
    }

    // Read another buffer
    piSocket = dwUserData == ReadFromInternal ?
        GetInternalSocket() : GetExternalSocket();

    if (piSocket == NULL) {
        return S_OK;
    }

    piSocket->Recv(NULL, this, dwUserData);

    piSocket->Release();

    return S_OK;
}


IFWXIOCompletion

All overlapped operations require the filter to implement this interface to carry out data pumping.

Notes to Implementers

When calling a method that begins an overlapped operation, the filter must pass to that method a pointer to the IFWXIOCompletion interface. The Firewall service calls the IFWXIOCompletion interface of the filter when the overlapped operation completes.

ISA Samples that Use IFWXIOCompletion Methods

The method IFWXIOCompletion::CompleteAsyncIO is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

Example Code

See Simple Implementation of CompleteAsyncIO in the IFWXDataFilter topic earlier in this section.


IFWXConnection

The connection object represented by the IFWXConnection interface implements functions specific to a particular connection. Each remote socket created for a client has a connection object associated with it.

The IFWXConnection methods are understood most easily in the context of connection scenarios:

Scenario A: Bind/Connect

  1. The client requests a bind or connection.
  2. The Firewall service creates a Connection object.
  3. The Firewall service checks access rights.
  4. The Firewall Service provides an event notification to the application filters, so that the filters can then work with the Connection object and use:
    • IFWXConnection::Deny to deny the connection.
    • IFWXConnection::AttachDataFilter to attach a data filter to this connection. In the case of a bind request, this applies to UDP only.
    • IFWXConnection::SetProtocol to establish that the connection is for a particular protocol, and to inform the Firewall service whether the connection will be emulated.

Scenario B: Bind/Listen

  1. The client requests a bind.
  2. The filter calls IFWXSession::BindForClient.
  3. The Firewall service creates a Connection object.
  4. The Firewall service provides an event notification to the application filter, so that the filter can then work with the Connection object.

When a listening socket exists, and a fwx_AcceptedConnection event occurs, an accepted socket is created on the Firewall service. The Connection object for the accepted socket exists before the matching client socket is created.

Notes to Implementers

When a registered event occurs, the Firewall service will call FwxFirewallEventHandler and will pass the FirewallEvent parameter to it. Included in the FirewallEvent parameter is a pointer to IFWXConnection.

After the pointer is available you can use the methods such as IFWXConnection:AttachDataFilter.

Sample Filters that Use IFWXConnection Methods

The method IFWXConnection::AttachDataFilter is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock

The method IFWXConnection::GetExternalSocketName is used in the following sample provided with ISA:

  • ConnectorFilter

The method IFWXConnection::Deny is used in the following samples provided with ISA:

  • ExeBlock
  • ServerSplit

The method IFWXConnection::EmulateConnection is used in the following sample provided with ISA:

  • ServerSplit

The method IFWXConnection::SetProtocol is used in the following samples provided with ISA:

  • ServerSplit
  • SMTPFLTR

The method IFWXConnection::SetSocketName is used in the following sample provided with ISA:

  • ServerSplit

Typical Implementations

Implemented by the Firewall service.


IFWXUdpDestination

The IFWXUdpDestination interface controls the outcome of a UDP destination event.

Notes to Implementers

Use IFWXUdpDestination::Deny to block the destination. Call IFWXUdpDestination::SetProtocol to associate the destination with the given protocol and perform access control based on the user's permission to access the protocol.

Typical Implementations

Implemented by the firewall service.


IFWXSocket

The IFWXSocket interface is the Firewall service socket interface. This interface does not create the socket; rather, it allows the data filter to work with data that is flowing through the socket.

The socket itself is created by using the IFWXNetworkSocket interface.

For more information on sockets and socket interfaces, see Socket Objects.

Samples that Use IFWXSocket Methods

The method IFWXSocket::Close is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSocket::Recv is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSocket::Send is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXSocket::SendTo is used in the following samples provided with ISA:

  • DbgDump
  • ServerSplit

The method IFWXSocket::Shutdown is used in the following samples provided with ISA:

  • DbgDump
  • ServerSplit

Typical Implementations

Implemented by the Firewall service.


IFWXIOBuffer

The buffer class holds a reference-counted memory buffer. The IFWXOBuffer object is a wrapper around a memory buffer. This allows the buffer to be used by many filters in a chain, avoiding inefficient copying of buffers. For more information on memory buffers, see Buffer Objects.

Notes to Implementers

Consider carefully the size of the buffer needed. Data length information provided on the Internet may be inaccurate, resulting in buffer overload.

IFWXIOBuffer is generally implemented by the Firewall service. However, you may want the filter to implement IFWXIOBuffer in either of the following circumstances:

  • You already have an allocated buffer that you want to send, and you want to avoid a buffer copy. For example, the buffer was received from an RPC call or an API that cannot work with Firewall service buffers.
  • You want to import data into a preallocated buffer.

You can rely on the Firewall service's implementation of IFWXIOBuffer, and not code a filter implementation, if:

  • You want to send a constant buffer.
  • You want to send a section of another buffer.
  • Your filter can handle or parse the data from IFWXIOBuffer.
  • Buffer copy is not of concern.

Samples that Use IFWXIOBuffer Methods

The method IFWXIOBuffer::Append is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • ExeBlock

The method IFWXIOBuffer::GetBufferAndSize is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXIOBuffer::SetDataSize is used in the following sample provided with ISA:

  • ExeBlock


IFWXFirewall

The IFWXFirewall interface provides functions for filters that are not tied to any specific user session.

The Firewall service implements this interface and passes it to the IFWXFilter::FilterInit method.

Notes to Implementers

The IFWXFirewall::DuplicateFilterHookEvents method is used in every filter. For a usage example see IFWXFilter::FilterInit.

Samples that Use IFWXFirewall Methods

The method IFWXFirewall::CreateBuffer is used in the following sample filters provided with ISA:

  • ConnectorFilter
  • ExeBlock

The method IFWXFirewall::DuplicateFilterHookEvents is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXFirewall::CreateConstBuffer is used in the following sample provided with ISA:

  • ExeBlock

The method IFWXFirewall::CreateNetworkSocket is used in the following sample provided with ISA:

  • ServerSplit

The method IFWXFirewall::CreateOverlapped is used in the following sample provided with ISA:

  • ExeBlock

The method IFWXFirewall::HookToCompletionPort is used in the following sample provided with ISA:

  • ExeBlock

The method IFWXFirewall::GetPNATSession is used in the following sample provided with ISA:

  • SMTPFLTR

Typical Implementations

Implemented by the Firewall service.


IFWXSession

The IFWXSession interface is used to attach a data filter to a session and to monitor the session's events.

The session object implements session-specific functions that impersonate the user's account, test ACLs against the session's user, get information about the client computer, and perform protocol operations.

Samples that Use IFWXSession Methods

The method IFWXSession::AccessCheck is used in the following sample filter provided with ISA:

  • ExeBlock

The method IFWXSession::AllowFutureConnect is used in the following sample provided with ISA:

  • ConnectorFilter

The method IFWXSession::BindForClient is used in the following sample provided with ISA:

  • ConnectorFilter
  • SMTPFLTR

The method IFWXSession::GetClientAddress is used in the following sample provided with ISA:

  • DbgDump

The method IFWXSession::GetClientMachineName is used in the following sample provided with ISA:

  • DbgDump

The method IFWXSession::GetSessionFlags is used in the following sample provided with ISA:

  • ConnectorFilter

The method IFWXSession::RetroactiveAllowBind is used in the following sample provided with ISA:

  • ConnectorFilter

Typical Implementation

Implemented by the Firewall service.


IFWXFilterAdmin

The IFWXFilterAdmin interface is used by the filter for installation and configuration. You must use this interface to install a filter.

Notes to Implementers

Create an instance of the FWXFilterAdmin class to use these administration methods.

ISA Samples that Use IFWXFilterAdmin Methods

The method IFWXFilterAdmin::InstallFilter is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXFilterAdmin::UninstallFilter is used in the following samples provided with ISA:

  • ConnectorFilter
  • DbgDump
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXFilterAdmin::RegisterProtocolForFilter is used in the following samples provided with ISA:

  • ConnectorFilter
  • ExeBlock
  • ServerSplit
  • SMTPFLTR

The method IFWXFilterAdmin::UnregisterProtocolForFilter is used in the following sample provided with ISA:

  • SMTPFLTR

The method IFWXFilterAdmin::GetProtocol is used in the following samples provided with ISA:

  • ConnectorFilter
  • SMTPFLTR

The method IFWXFilterAdmin::GetFilterParameterSet is used in the following sample provided with ISA:

  • SMTPFLTR

Example Code

The code for registering filters and protocols should be written in the .cpp file that represents the filter object. The filter uses this interface primarily in the DllInstall function.

Code for Registering the Filter

static HRESULT RegisterApplicationFilter(int fRegister, FwxScope Scope)
{
    HRESULT hr;
    CComPtr<IFWXFilterAdmin> pIFWXFilterAdmin;
    MSNEROOT::IFPCPtr comptrIFPC;
    MSNEROOT::IFPCEventDefinitionPtr  comptrIFPCEventDefinition;
    MSNEROOT::IFPCFilterProtocolPtr comptrIFPCFilterProtocol;

    hr = CoCreateInstance (CLSID_FWXFilterAdmin,
                           NULL,
                           CLSCTX_SERVER,
                           IID_IFWXFilterAdmin,
                           (LPVOID *) &pIFWXFilterAdmin);
    if (FAILED(hr))
        return hr;
}

Code for Protocol Registration

// HRESULT hr;
// IFWXFilterAdmin *ifa;

hr = ifa->RegisterProtocolForFilter(
    CLSID_FTPFilter,
    L"FTP",
    L"FTP protocol via ftpfltr filter",
    NULL,
    Scope);


Advanced Filter Interfaces

In addition to the 11 interfaces described in Basic Filter Interfaces, there are nine interfaces that provide additional functionality for application filters:

Interface | Implementation
IFWXAcceptCompletion | Implemented by the application filter.
IFWXExternalIOCompletion | Implemented by the application filter.
IFWXImpersonator | Implemented by the application filter.
IFWXNetworkSocket | Implemented by the Firewall service.
IFWXOverlapped | Implemented by the Firewall service.
IFWXFirewallAction | Implemented by the Firewall service.
IFWXGetXByY | Implemented by the Firewall service.
IFWXSlowDataFilter | Implemented by the application filter.
IFWXIpFilter | Implemented by the firewall service.


IFWXAcceptCompletion

The IFWXAcceptCompletion interface has one method, CompleteAsyncAccept. This method receives notifications from the Firewall service when an IFWXNetworkSocket:Accept method is completed on a listening socket. For more information, see IFWXAcceptCompletion::CompleteAsyncAccept in the Reference section.

Typical Implementations

Implemented by the application filter.


IFWXExternalIOCompletion

The IFWXExternalIOCompletion interface has one method, CompleteAsyncIO. This method receives notifications from the Firewall service when an asynchronous I/O operation on an operating system file (such as writing to or reading from a disk) is completed. For more information, see IFWXExternalIOCompletion::CompleteAsyncIO in the Reference section.

Typical Implementations

Implemented by the application filter.

Example Code

This example of an implementation of IFWXExternalIOCompletion::CompleteAsycnIO is taken from the Exeblock sample filter.

HRESULT
STDMETHODCALLTYPE
CEBScannerDataFilter::CompleteAsyncIO(
    /* [in] */ BOOL fSuccess,
    /* [in] */ DWORD NumberOfBytesTransfered,
    /* [in] */ DWORD Win32ErrorCode,
    /* [in] */ IFWXOverlapped __RPC_FAR *pOverlapped,
    /* [in] */ UserContextType UserData)
{

    if (!fSuccess) _Abort();
    pOverlapped->Release();
    IFWXSocket *pISocket = _GetExternalSocket();

    if (pISocket) {
        pISocket->Recv(NULL, this, 0);
        pISocket->Release();
    }

    return S_OK;
}

ISA Samples that Use IFWXExternalIOCompletion Methods

The method IFWXExternalIOCompletion::CompleteAsyncIO is used in the following sample provided with ISA:

  • Exeblock


IFWXImpersonator

The IFWXImpersonator object holds user information so that the Firewall service can impersonate the user. Impersonators are typically implemented by the Firewall service, as in the case when the service is performing an access check. This holds true for sessions created by the firewall service. When a session has been created by a filter using the IFWXFirewall::CreatePrivateSession method, impersonation is performed by the application filter on behalf of the Firewall service through IFWXImpersonator.

Impersonators must be implemented as in-process servers.

Notes to Implementers

The filter can implement IFWXImpersonator when using a private session if the filter can authenticate the user. The authentication may be on the protocol level, or for out-of-band communication.

For more information about private sessions, see IFWXFilter::CreatePrivateSession.

Typical Implementations

Implemented by the Firewall service.

Example Code

class CFWXImpersonator :
    public CComObjectRootEx<CComMultiThreadModel>,
    public IFWXImpersonator {

public:

    BEGIN_COM_MAP(CFWXImpersonator)
        COM_INTERFACE_ENTRY(IFWXImpersonator)
    END_COM_MAP()

    // IFWXImpersonator
    HRESULT STDMETHODCALLTYPE Impersonate(void) {
        HRESULT hr = S_OK;
            if (!ImpersonateLoggedOnUser(m_token)) {
            hr = HRESULT_FROM_WIN32(GetLastError());
            }
        return hr;
    }

    HRESULT STDMETHODCALLTYPE RevertToSelf(void) {
        HRESULT hr = S_OK;
            if (!RevertToSelf()) {
            hr = HRESULT_FROM_WIN32(GetLastError());
            }

        return hr;
    }

    // Initialize from a token handle
    HRESULT Initialize(HANDLE token) { m_token = token; return S_OK; }
    // Initialize from username + password
    HRESULT Initialize(LPCSTR UserName, LPCSTR Domain, LPCSTR Password) {
             if (LogonUser(
                 UserName,
                 Domain,
                 Password,
                 LOGON32_LOGON_NETWORK,
                 LOGON32_PROVIDER_DEFAULT,
                 &m_hToken)) return S_OK;
             else {
                 return HRESULT_FROM_WIN32(GetLastError());
             }
    }
private:
    HANDLE m_token;
};


IFWXNetworkSocket

The IFWXNetworkSocket interface is an extension of the IFWXSocket interface. IFWXNetworkSocket represents a true socket object for either the client or server. The socket object for IFWXNetworkSocket can be created by using either IFWXFirewall::CreateNetworkSocket or IFWXSession::CreateNetworkSocket. For more information see Socket Implementation in ISA, or IFWXNetworkSocket.

ISA Samples that Use IFWXNetworkSocket Methods

The method IFWXNetworkSocket::Accept is used in the following sample filter provided with ISA:

  • ServerSplit

The method IFWXNetworkSocket::Bind is used in the following sample provided with ISA:

  • ServerSplit

The method IFWXNetworkSocket::Listen is used in the following sample provided with ISA:

  • ServerSplit

Typical Implementations

Implemented by the Firewall service.


IFWXOverlapped

If the Firewall service is performing asynchronous I/O for an operating system file, it must have access to the Windows Sockets OVERLAPPED structure and a means of setting up a callback when the I/O is completed.

IFWXOverlapped gets a pointer to the Windows Sockets OVERLAPPED structure. The IFWXOverlapped object also provides the link between the OVERLAPPED structure and a completion notification interface and includes user context information that allows the filter to distinguish between different notifications.

Notes to Implementers

First use the IFWXOverlapped::SetNotificationInterface method to set the notification interface and user-context. Then use the IFWXOverlapped::GetOverlapped method to get an OVERLAPPED structure that will be used in a call to an asynchronous Win32 API.

The call to the WIN32 API must use a handle that is associated with the Firewall service's completion port. For more information, see IFWXFirewall::HookToCompletionPort.

When the overlapped operation completes, the Firewall service will get the completion notification in its completion port and will call the completion notification method of the specified interface.

Samples that Use IFWXOverlapped Methods

The method IFWXOverlapped::GetOverlapped is used in the following sample filter provided with ISA:

  • ExeBlock

The method IFWXOverlapped::SetNotificationInterface is used in the following sample provided with ISA:

  • ExeBlock


IFWXFirewallAction

A filter may request that the Firewall service perform a firewall action, such as connecting to a certain target, in response to a firewall event or address. A firewall action is always requested in anticipation of an event that may not occur. This interface permits cancellation of the firewall action request. Typically, a firewall action relates only to events for which a filter is not registered.

For example, if the action is the future establishment of a secondary connection, IFWXFirewallAction can be used to cancel the action if the primary connection is terminated.

Remarks

The firewall may automatically cancel certain actions, including:

  • Actions that are supposed to happen only once (the action is canceled after its first occurrence).
  • Actions that have a time-out.
  • An action associated with a session that has been killed.

ISA Samples that Use IFWXFirewallAction Methods

The method IFWXFirewallAction::Cancel is used in the following sample filter provided with ISA:

  • ConnectorFilter

Typical Implementations

Implemented by the Firewall service.


IFWXGetXByY

IFWXGetXByY allows you to override the gethostbyname or gethostbyaddr function. A typical use of IFWXGetXByY is to return an IP address other than that requested by the client, thus redirecting the request. IFWXGetXByY can also cause the gethostbyname and gethostbyaddr functions to fail, so that the Firewall service will return a "Host Not Found" message.

Notes to Implementers

The filter must call this interface from within the IFWXSessionFilter::FirewallEventHandler function.

Typical Implementations

Implemented by the application filter.


IFWXSlowDataFilter

A data-filter object may implement the IFWXSlowDataFilter interface to prevent premature termination of a connection.

When a Firewall client application calls the Windows Sockets WSACleanup function, the client DLL will close the Firewall service session. As a result, the Firewall service will terminate all connections that were created in this session.

In rare circumstances, this termination may lead to data loss if the client application relies on TCP/IP for receipt acknowledgement. The connection can be closed after acknowledgment of a packet receipt because the slow connection delays receipt of the remaining packets. This is not a problem if the client application uses application-level acknowledgement.

To prevent data loss in these cases, implement the IFWXSlowDataFilter interface.


IFWXIpFilter

IFWXIpFilter is the application filter interface that represents an IP Filter: a range of IP addresses for which a connection or socket is allowed to function. Use this interface to ensure that secondary and emulated connections are secure.

Notes to Implementers

There are situations in which an application filter is responsible for limiting what IP addresses are allowed access to, including:

  • The case of a secondary inbound connection, as occurs in use of the FTP protocol
  • The case of a secondary or emulated connection in a publishing scenario.

For security purposes, the application filter has to define an IP filter: a range of IP addresses for which a particular connection or socket is allowed. The IFWXIpFilter interface is where you define that range of IP addresses.

An IP filter created by using the IFWXIpFilter interface is no more than a definition of IP ranges. The mechanism that provides the filtering functionality is the ISA server packet filtering mechanism. Therefore, an IP Filter defined by using IFWXIpFilter will not function unless IP packet filtering is enabled in ISA. For more information about packet filtering, see IP Packet Filtering, or the ISA Server product documentation.

Note If you set the range of IP addresses equal to NULL, you are allowing all addresses to connect.

Typical Implementations

Implemented by the Firewall service.


Filter Development Process

The filter development process is described here in general terms. For more specific information, review the procedure in How to Create an Application Filter. In describing this process, use of the Visual Studio Active Template Library (ATL) is assumed and recommendedbecause it handles much routine work for the project.

Application filters typically require these procedures:

  • Create the necessary COM objects Typically, these are the filter object, session filter object, and data filter object.
  • Monitor events
  • Attach the filter to a session
  • Process data
  • Provide code to register and unregister the filter
  • Installation

Note Filters must be registered as COM servers and in the ISA configuration.


Best Practices

The best practices provided here will help you create more efficient application filters.

Registration for Events

  • Register for as small a set of events as possible. This is true for first-phase events registered in IFWXFilter::FilterInit and for events registered in IFWXFilter::AttachToSession. Unnecessary event registrations increase the load on the Firewall service and reduce performance.
  • In IFWXFilter::AttachToSession, don't define explicit data filters unless monitoring or modification of the stream is really needed. This allows the Firewall service to do the data pumping in kernel mode, which is more efficient than the user-mode data pumping of data filters.

Buffers and Data

  • Copying data reduces performance, so avoid copying I/O buffer content. Instead, use the methods of the IFWXIOBuffer interface to manage data buffers. To avoid copying buffers, a filter should call IFWXSocket::Recv, specifying NULL as the buffer. This causes the Firewall service to pass to the filter an existing buffer, instead of copying from the existing buffer to the filter's buffer.

Threading

  • If your filter performs asynchronous I/O on operating-system files, use the completion notification mechanism provided by ISA. For more information, see Completion Notification Objects.
  • Call the IFWXFirewall::StartHeavyBlockingOperation method before making a blocking operation. When this method is used, the Firewall service keeps track of the number of threads that are busy with blocking operations and creates new threads when necessary.
  • Do not call IFWXFirewall::StartHeavyBlockingOperation before waiting for a critical section or a resource on which other threads are likely to be blocked. If the newly created thread is blocked on the same critical section, there will be greater congestion on the critical section and more context switches, resulting in an overall reduction in performance.
  • Expect methods to be called from different threads simultaneously. If more than one thread accesses data at the same time, the data can be left in an inconsistent state. You can prevent this by using critical sections, which allow only one thread at a time to use the protected code section. Examples of the use of critical sections can be seen in the sample application filters provided with the ISA SDK. For more information on critical sections, see MSDN.
  • Similarly, you can use interlocked functions, which synchronize access to a variable that is shared by multiple threads. Interlocked functions prevent a thread from being preempted when it is in the middle of incrementing or checking a variable. For more information on critical sections, see MSDN.
  • In general, when calling a method of an object that may call back the calling object (either on the same thread or by waiting for another thread to perform the callback), a deadlock may arise. Therefore, avoid holding locks while calling methods of Firewall service-implemented objects.

    For example, there may be a race between calls to Detach (IFWXDataFilter::Detach, or IFWXSessionFilter::Detach) and other methods. Data filters receive IFWXSocket interfaces when the IFWXDataFilter::SetSockets API is called. Because the Firewall service is multithreaded, more than one thread can use the same IFWXSocket interface simultaneously. Furthermore, one thread may call Detach to release the IFWXSocket interface, while the other thread still attempts to access the interface, perhaps while doing a data-pump. Access to the interface should be protected by a locking mechanism, such as a critical section. Because of locking by the Firewall service, deadlock situations may arise; for example, the following code can lead to a deadlock situation:

    Lock();
HRESULT hr = spSocket->Close(FALSE);
Unlock();

    To avoid the deadlock, use this code:

    // Copy member pointer to interface to a local "smart" pointer
// while the object is locked
CComPtr<IFWXSocket> spSocket;
Lock();
spSocket = m_InternalSocket;
Unlock();   // lock released to avoid deadlocks

// Must verify that interface was not released by Detach()
if (spSocket != NULL) {
// Here it is safe to send, receive or close the socket.
HRESULT hr = spSocket->Close(FALSE);
}
  • Avoid creating too many threads in the Firewall service. If you create a thread that waits for an infrequent event, such as a configuration change, use the Win32 function RegisterWaitForSingleObject. If you create a thread to perform periodic tasks that will spend most of its time sleeping, use the Win32 function CreateTimerQueueTimer. Each of these functions uses thread pools to reduce the number of threads that are busy at one time.

Security for Secondary and Emulated Connections

There are situations in which an application filter is responsible for limiting what IP addresses are allowed access to, including:

  • The case of a secondary inbound connection, as occurs in use of the FTP protocol.
  • The case of a secondary or emulated connection in a publishing scenario.

For security purposes, the application filter has to define a range of IP addresses for which a particular connection is allowed. Define that range of IP addresses by using the IFWXIpFilter interface.

Note If you set the range of IP addresses equal to NULL, you are allowing all addresses to connect.


Application Filter Test Environment

After you've developed an application filter, you will want to test it in a laboratory setting. To do this, configure the lab to represent a network/ISA-server/Internet situation:

Lab Configuration

Three computers are required to test application filters. One computer functions as the ISA server. This computer must have two network interface cards (NICs). Connect one card to a computer representing the internal client and the other to a computer representing the Internet.

The specific lab requirements will depend on the type of filter you are testing. For an example of a specific test setup and procedure, see SMTPFLTR Test Environment.


Filter Setup

You must install filters on the ISA Server computer, where they must reside locally. Filters must be registered as COM servers and in the ISA configuration.

Filters that register a protocol need to have the protocol registered on the enterprise level. This is particularly important in a situation where only enterprise policy is used. Developers of application filters should therefore provide two installation facilities, one for installing a filter in the array, and one for registering the filter at the enterprise level.

The registration process includes the following steps:

  1. Copying the DLLs and any other necessary files to the ISA Server computer (array setup only).
  2. Registering the COM objects. The registration is typically implemented in the DllRegisterServer function, which can be activated by the RegSvr32 utility.
  3. Register the filter in ISA Storage as an application filter for the firewall service, on either the enterprise or array level by using IFWXFilterAdmin::InstallFilter. You should implement this step using the DllInstall function. Whether the filter is installed on the enterprise or array level will depend on the command-line parameters used with DllInstall, as shown in the Setup Examples.
  4. Register the filter protocols, primary connection ports, and alert events, as necessary.

Note When an ISA administrator installs a filter on ISA servers, there may be functions that should be performed during the first installation of the filter on a server, such as IFWXFilterAdmin::RegisterProtocolForFilter. More importantly, during uninstallation there may be functions that should only be performed by the last uninstallation, such as IFWXFilterAdmin::UnregisterProtocolForFilter. In that case, the protocol might be unregistered while filters on some servers still require that the protocols be registered. For this reason, when you develop a filter, you should consider using a mechanism to synchronize filter installation in an array.

One solution is to use the VendorParametersSets collection (accessed through the FPCServer.VendorParametersSets property) to write to the server storage a value under the vendor name and filter GUID. The server storage will thus have a record that the filter is installed, and your filter can use that information to keep track of its relative order in the installation or uninstallation process.

Setup Examples

Provided here are examples of the commands used to perform application filter setup on the array and enterprise level.

Setup on array

To set up the application filter on an array

  1. Copy the DLL to the ISA Server computer
  2. Call DllRegisterServer.
  3. Call DllInstall(TRUE, L"array")

As an alternative to steps 2 and 3, you can run:

regsvr32 /i:array mydll.dll

Setup on enterprise

To set up the application filter on an enterprise

  • Call DllInstall(TRUE, L"enterprise") or run regsvr32 /n /i:enterprise mydll.dll

Note There is no need to install the DLL on the computer.

Uninstall on array

To uninstall an application filter from an array

  1. Call DllInstall(FALSE, L"array")
  2. Call DllUnregisterServer

As an alternative to these two steps you can run:

regsvr32 /u /i:array mydll.dll

Uninstall on enterprise

To uninstall an application filter from an enterprise

  • Call DllInstall(FALSE, L"enterprise") or run regsvr32 /u /n /i:enterprise mydll.dll

Note Because the filter objects are created when the Firewall service starts, the server must be stopped and then restarted after setup is completed.

The RegSvr32 utility is not a required part of the setup. A setup utility can use RegSvr32, or load the DLL and call the registration code directly.

Services may not have the necessary permissions to allow them to write vendor-specific information to the DS. For this reason, you should perform the saving of vendor parameters to ISA during filter setup.


Example Code

For an example of filter registration code, see Add the Registration Code in How to Create an Application Filter.

The code for event registration can be written in the context of the filter registration code.

The code for registering filters and protocols should be written in the FilterName.cpp file.


How to Create an Application Filter

This section describes how to create an SMTP application filter, which captures and analyzes data sent by external clients.

A step-by-step example shows you how to create an SMTP filter. To simplify the procedure, this particular filter does not have complete SMTP filtering functionality. The filter can search for a particular string, but it does not act based on that string. A fully functional SMTP filter is provided with ISA Server, and a sample SMTP filter is provided with the ISA SDK. Comparison of the code in this section with the code in the sample SMTP filter will highlight where the filter code should be placed.

The sample SMTP filter demonstrates the use of a data filter factory, not shown in this step-by-step example.

The example consists of the sequential steps in the following sections:

  • Creating the Filter
  • Attach a Session Filter to a Firewall Session
  • Add Registration Code and Register the Filter
  • Add SMTP Content Filtering Using the IFWXDataFilter Interface
  • Reading Configuration from Vendor Parameter Sets
  • Raising an Event When a String is Found


Creating the Filter

To follow the procedures in this section, use the Visual C++ Active Template Library (ATL) wizards to create the SMTP filter. In the Integrated Development Environment (IDE) wizard dialog boxes, use default settings unless otherwise specified. This procedure assumes that the filter classes were not previously registered on the computer where the filter is being built.

This section contains two procedures:

  • Creating the COM Filter Object
  • Creating a Filter Object that Monitors AcceptedConnection Events


Creating the COM Filter Object

To begin developing an application filter, create a new project, and then include the necessary header and .idl files. For more information about these declaration files, see Header and .Idl Files Provided with ISA.

To create the COM filter object

  1. Create a new project (using the ATL COM AppWizard) with the following properties:
    • Name — SMTPFLTR
    • Server Type — DLL
  2. Add the header and .idl files to the project.

    In the Project Settings dialog box, in the Settings For drop-down menu, select All Configurations. Then, select the C/C++ tab, and from the Category drop-down menu select Preprocessor. In the Additional include directories entry field, add the path to the SDK inc directory to the include path of the project. Type the same path information in the Additional include directories entry field of the MIDL tab, and click OK.. Then add wspfwext.idl and msfpccom.idl from ISA SDK's inc directory to the project's source files.

    To include all the interface definitions and their GUIDs that are required to build a filter (for example, IFWXFilter, IFWXSessionFilter, or IFWXDataFilter), import wspfwext.idl at the beginning of the SMTPFLTR.idl file:

    import "oaidl.idl";        // line produced by the wizard
import "ocidl.idl";        // line produced by the wizard
import "wspfwext.idl";     // you add this line

    The build process produces other files, such as wspfwext.h and wspfwext_i.c.

  3. Build the project.
  4. Add include statements.

    The header file wspfwext.h contains the definitions of all necessary filter interface methods (IFWXFilter, IFWXSessionFilter, and so on). Add an include statement for wspfwext.h to the precompiled header file stdafx.h:

    #include "wspfwext.h"

    The MIDL-generated file wspfwext_i.c contains predefined GUIDs for the filter interfaces. Include it in one of the .cpp files, for example SMTPFLTR.cpp.

    #include "wspfwext_i.c"


Creating a Filter Object that Monitors AcceptedConnection Events

You need to create a filter object that will implement the IFWXFilter interface. This interface is necessary for the creation of a filter. The filter object will monitor fwx_AcceptedConnection events.

Warning Visual C++ will not create a new ATL object if more than one .idl file is included in your project. Delete all the .idl files except SMTPFLTR.idl from the project, add the ATL object as described in step 1, and then replace the .idl files that you removed.

To create the filter object

  1. Create a COM object that implements the IFWXFilter interface.

    Insert a new ATL object (Simple Object), with the following properties:

    • Short Name — SMTPFilter
    • Interface — IFWXFilter
    • Attributes:

      Threading Model — Free

      Interface — Custom

      Aggregation — No

  2. Edit the SMTPFLTR.idl file. Because the IFWXFilter interface and its GUID are already defined in wspfwext.idl, you must delete the IFWXFilter definition code that is produced in SMTPFLTR.idl by the wizard. Note that the UUID in this code is only provided as an example.
    [
        uuid(20F10C85-2C5E-11D2-8C3D-006094EB63EF),

        helpstring("IFWXFilter Interface"),
        pointer_default(unique)
]
interface IFWXFilter : IUnknown
{
};
  3. Add declaration of IFWXFilter methods. Use wspfwext.h to get the prototypes of the methods of IFWXFilter and add them to the public section of the class definition in SMTPfilter.h. Note that you must remove =0 from the methods. Insert the following code:
    // IFWXFilter
    virtual HRESULT STDMETHODCALLTYPE FilterInit(
    /* [in] */ IFWXFirewall __RPC_FAR *pIFWXFirewall,
    /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents);

    virtual HRESULT STDMETHODCALLTYPE FilterShutdown(void);

    virtual HRESULT STDMETHODCALLTYPE AttachToSession(
    /* [in] */ IFWXSession __RPC_FAR *piSession,
    /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
    /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents);
  4. Add the implementation of IFWXFilter methods. Use wspfwext.h to get the prototypes of the methods of IFWXFilter and add them to SMTPfilter.cpp with implementation code.

    Start with a simple implementation, for example:

    return E_NOTIMPL;

    The implementation code should look like this:

    // CSMTPFilter

    HRESULT STDMETHODCALLTYPE CSMTPFilter::FilterInit(
            /* [in] */ IFWXFirewall __RPC_FAR *pIFWXFirewall,
            /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
    {
        return E_NOTIMPL;

    }

    HRESULT STDMETHODCALLTYPE CSMTPFilter::FilterShutdown( void)
    {
        return E_NOTIMPL;

    }

    HRESULT STDMETHODCALLTYPE CSMTPFilter::AttachToSession(
        /* [in] */ IFWXSession __RPC_FAR *piSession,
        /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
        /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
    {
        return E_NOTIMPL;

    }
  5. Build the project.
  6. Add the SMTPFilter object constructor code, and implement the IFWXFilter::FilterInit method. The Firewall service calls this method on startup. In the IFWXFilter::FilterInit method you will save a reference to the IFWXFirewall interface to be used later. Then you will define the set of initial events that the filter will monitor. This example monitors the fwx_AcceptedConnection and fwx_Bind_Tcp events. However, for performance reasons it is better to monitor a minimal set of events at the IFWXFilter level. Therefore, your filter will monitor the fwx_Bind_Tcp events for port 25 and when they occur it will also monitor fwx_AcceptedConnection events. You also must define the port from which you want to receive events. In this example the port is 25.

    In SMTPfilter.h, add the following code:

    private:
    CComPtr<IFWXFirewall>    m_pIFWXFirewall;
    FwxFilterHookEvents      m_FwxFilterHookEvents;
    FwxPortRangeEvents       m_FwxPortRangeEvents;

    In SMTPfilter.h, locate the default object constructor code, and remove the default implementation ({}) and add a semicolon as shown:

        CSMTPFilter();
    {
    }

    and place the following object constructor code and FilterInit implementation in SMTPFilter.cpp:

    CSMTPFilter::CSMTPFilter ()
{
    m_FwxPortRangeEvents.StartPort = 25;
    m_FwxPortRangeEvents.EndPort  = 25;
    m_FwxPortRangeEvents.dwSocketEvents =
        FWX_ALL_SOURCES // Event Source is either NAT or Firewall client
        | fwx_Bind_Tcp;//At this level, monitor binds

    m_FwxFilterHookEvents.dwGlobalEvents        = 0;
    m_FwxFilterHookEvents.dwNumPortRanges       = 1;
    m_FwxFilterHookEvents.FwxPortRangeEvents    = &m_FwxPortRangeEvents;
}

HRESULT STDMETHODCALLTYPE CSMTPFilter::FilterInit(
    /* [in] */ IFWXFirewall __RPC_FAR *pIFWXFirewall,
    /* [out] */ FwxFilterHookEvents __RPC_FAR *__RPC_FAR *ppFilterHookEvents)
{
    m_pIFWXFirewall = pIFWXFirewall;
    return m_pIFWXFirewall->DuplicateFilterHookEvents (&m_FwxFilterHookEvents, ppFilterHookEvents);
}
  7. Implement the IFWXFilter::FilterShutdown method. This is a request to the filter to shut down. Because this filter doesn't hold a reference to any object except the firewall callback interface, it can simply return S_OK. The implementation should be in SMTPfilter.cpp, in place of the previously inserted implementation of return E_NOTIMPL.
    HRESULT STDMETHODCALLTYPE CSMTPFilter::FilterShutdown( void)
{
    return S_OK;
}
  8. Build the project.


Attach a Session Filter to a Firewall Session

The Firewall service uses IFWXFilter::AttachToSession to inform the filter that an event it is registered for has occurred. The filter then must create an object that implements the IFWXSessionFilter interface.

This section contains three procedures that you must follow in order to attach a session filter to a firewall session:

  1. Create an IFWXSessionFilter COM Object
  2. Implement the IFWXFilter::AttachToSession Method
  3. Add the Definition and Implementation of IFWXSessionFilter Methods


Create an IFWXSessionFilter COM Object

In this procedure, you will implement the following methods:

  • IFWXSessionFilter::FirewallEventHandler
  • IFWXSessionFilter::Detach

In the following steps you will use the ATL Object Wizard to create the skeleton for the new object. Because this object doesn't have to be created outside the filter, you can reduce the size of your code by removing ATL-generated code that supports the CoCreateInstance function or other COM mechanisms to create objects. To avoid having to edit the files that were edited in the case of the IFWXFilter interface, back up the current versions, and restore them after you add the new object.

Warning Visual C++ will not create a new ATL object if more than one .idl file is included in your project. Delete all the .idl files except SMTPFLTR.idl from the project, add the ATL object as described, and then put back in the .idl files that you removed.

To create the FWXSessionFilter object

  1. Make a copy of these files: SMTPFLTR.rc, resource.h, SMTPFLTR.idl, and SMTPFilter.cpp.
  2. Insert a new ATL object (Object — Simple Object) with the following properties:
    • Short Name — FWXSessionFilter
    • Interface — IFWXSessionFilter
    • Attributes:

      Threading Model — Free

      Interface — Custom

      Aggregation — No

  3. Cleanup:
    • Restore the files: SMTPFLTR.rc, resource.h, SMTPFLTR.idl, and SMTPFilter.cpp.
    • Delete fwxsessionfilter.rgs and remove it from the project workspace.
    • From FWXSessionFilter.h delete the lines
      public CComCoClass<CFWXSessionFilter, &CLSID_FWXSessionFilter>,
DECLARE_REGISTRY_RESOURCEID(IDR_FWXSESSIONFILTER)


Implement the IFWXFilter::AttachToSession Method

The Firewall service calls the IFWXFilter::AttachToSession method when a registered event of the filter occurs (as defined in FilterInit). The COM method CComObject<>::CreateInstance is similar to the CoCreateInstance function, but only creates an instance of the class (with a reference count equal to 0) and does not need a GUID to do so. Add the following code to SMTPFilter.cpp, in place of the simple implementation you inserted earlier:

HRESULT STDMETHODCALLTYPE CSMTPFilter::AttachToSession(
    /* [in]  */ IFWXSession __RPC_FAR *piSession,
    /* [out] */ IFWXSessionFilter __RPC_FAR *__RPC_FAR *piSessionFilter,
    /* [out] */ PFwxFilterHookEvents __RPC_FAR *ppFilterHookEvents)
{
    OutputDebugString ("FWXFilter::AttachToSession\n");

    HRESULT hr = S_OK;

    CComObject<CFWXSessionFilter> *pSessionFilter;
    CComPtr<IFWXSessionFilter> spIFWXSessionFilter;

    //Create an instance of the session filter
    hr = CComObject<CFWXSessionFilter>::CreateInstance (&pSessionFilter);
    if (FAILED(hr))
        return hr;

    pSessionFilter->AddRef();

    hr = pSessionFilter->QueryInterface(IID_IFWXSessionFilter,
                                       reinterpret_cast<void**>(&spIFWXSessionFilter));
    pSessionFilter->Release();

    if(SUCCEEDED(hr))
    {
        //Define new set of events
        m_FwxPortRangeEvents.dwSocketEvents=FWX_ALL_SOURCES
                                         | fwx_AcceptedConnection
                                         | fwx_Bind_Tcp;

        hr = m_pIFWXFirewall->DuplicateFilterHookEvents (&m_FwxFilterHookEvents,
                                                     ppFilterHookEvents);
    }
    if (FAILED(hr))
        return hr;

    *piSessionFilter = spIFWXSessionFilter.Detach();
    return hr;
}

Add to smtpfilter.cpp the following include statement:

#include "FWXSessionFilter.h"


Add the Definition and Implementation of IFWXSessionFilter Methods

Now add the code to define and implement the IFWXSessionFilter methods. The methods are:

  • IFWXSessionFilter::FirewallEventHandler, which provides the event sink for firewall events relating to the session to which the session filter is attached
  • IFWXSessionFilter::Detach, which notifies the session filter to detach from a session.

To define and implement the IFWXSessionFilter methods

  1. Add the IFWXSessionFilter Method definitions:

    Use wspfwext.h to get the prototypes of the methods of IFWXSessionFilter and add them to fwxsessionfilter.h.

    Add the declaration of the methods to fwxsessionfilter.h, in the public section of the CFWXSessionFilter. The code should be:

    HRESULT STDMETHODCALLTYPE FirewallEventHandler(
        /* [ref][in] */ const FwxFirewallEvent __RPC_FAR *pFirewallEvent);

HRESULT STDMETHODCALLTYPE Detach( void);
  2. Add the IFWXSessionFilter method implementations:

    Copy the prototypes of the IFWXSessionFilter methods from wspfwext.h, and add them to fwxsessionfilter.cpp with implementation code.

    Start with a simple implementation in FWXSessionFilter.cpp; for example,

    return E_NOTIMPL;

    The implementation code should look like this:

    HRESULT STDMETHODCALLTYPE CFWXSessionFilter::FirewallEventHandler(
        /* [ref][in] */ const FwxFirewallEvent __RPC_FAR *pFirewallEvent)
{
    return E_NOTIMPL;

}

HRESULT STDMETHODCALLTYPE CFWXSessionFilter::Detach( void)
{
    return E_NOTIMPL;

}
  3. Build the project.
  4. Implement IFWXSessionFilter::FwxFirewallEventHandler:

    Add the IFWXSessionFilter::FwxFirewallEventHandler implementation to FWXSessionFilter.cpp, in place of the simple implementation:

    HRESULT STDMETHODCALLTYPE CFWXSessionFilter::FirewallEventHandler(
    /* [ref][in] */ const FwxFirewallEvent __RPC_FAR *pFirewallEvent)
{
    HRESULT hr = S_OK;

    switch (pFirewallEvent->EventType)
    {
    // Bind request for TCP sockets
    case fwx_Bind_Tcp:
        OutputDebugString ("IFWXSessionFilter::FirewallEventHandler – fwx_Bind_Tcp\n");
        OutputDebugString (FilterAccessString(
                           pFirewallEvent->
                           Parameters.Bind.FilterAccess));

        break;

    // Inbound connection on a listening TCP socket
    case fwx_AcceptedConnection:
        OutputDebugString ("IFWXSessionFilter::FirewallEventHandler – fwx_AcceptedConnection\n");
        OutputDebugString (FilterAccessString(pFirewallEvent->
 Parameters.Accept.FilterAccess));
        // The code for attaching a data filter that will do the actual
        //work will be placed here.
        break;

// Unexpected EventType
    default:
    OutputDebugString ("Error - FWXSessionFilter::FirewallEventHandler –Unexpected Event Type\n ");
        return E_FAIL;
    }

    return  hr;
}

    Also, add the FilterAccessString definition to FWXSessionFilter.cpp, immediately after the #include statements, as follows:

    // This function converts enum value to a corresponding string
static const char* FilterAccessString (int FwxFilterAccess)
{
    switch (FwxFilterAccess)
    {
        case FWX_ALLOW:
            return "Filter Access: FWX_ALLOW\n";
        case FWX_DENY:
            return "Filter Access: FWX_DENY\n";
        case FWX_PASS:
            return "Filter Access: FWX_PASS\n";
        case FWX_EMULATE:
            return "Filter Access: FWX_EMULATE\n";
    }
    return "Invalid Filter Access";
}
  5. Implement the IFWXSessionFilter::Detach method, in place of the simple implementation:

    Typically, the IFWXSessionFilter::Detach method is used to release references to other objects that must be released when the session ends. In this case, there are none:

    // Detach should return S_OK
HRESULT STDMETHODCALLTYPE CFWXSessionFilter::Detach( void)
{
    return S_OK;
}
  6. Build the project.


Add Registration Code and Register the Filter

In this section you will add the registration code for the filter. The registration code includes filter COM object, filter, and protocol registration.

Filter Object and Filter Registration

Filter object instances are created during the Firewall service startup. the code for registering the objects was automatically generated by ATL.

Filter registration uses the IFWXFilterAdmin::InstallFilter method and is implemented using the DllInstall function.

For more information on filter registration, see Filter Setup.

Protocol Registration

You need to manage network traffic through the filter. To do this, define a protocol for the filter to use and then create a protocol rule to allow that traffic. See the ISA product documentation for more information about protocol rules.

To define a protocol, call the IFWXFilterAdmin::RegisterProtocolForFilter function. After registering the protocol, you need to add the primary connection definition to the protocol.

Note You only need to define a protocol for Protocol-enabling filters. For more information see Filter Types.


Add the Registration Code

This section describes how to add the registration code to your filter.

To add the registration code

  1. In the Visual C++ Project Settings dialog box, select the C/C++ tab, and from the Category drop-down menu select Preprocessor. In the Additional include directories entry field, add to the include path of the project the appropriate directory for your compilation. This ensures that the compiler can find the msfpccom.tlb file (if the file is not located in a current include directory). Type the same path information in the Additional include directories entry field of the MIDL tab.
  2. In Project Settings, select the C++ tab, and in the C++ Language Category drop-down menu, click Enable Exception Handling, and click OK.
  3. Add the following code to StdAfx.h, before the #include Wspfwext.h directive:
    #import "msfpccom.tlb" rename_namespace("MSFPCCOM") named_guids
//define the GUID string with your filter GUID value
#define FILTER_GUID_STRING "{7CCF6FF0-D995-4da1-B452-4228047B2D1D}"
//define the FILTER_PROTOCOL_GUID
static const GUID FILTER_PROTOCOL_GUID = { 0x8226e96a, 0xb578, 0x4c28, { 0xb6, 0x86, 0x7e, 0xc9, 0x2b, 0xaf, 0x1e, 0xe7 } };
#define FILTER_PROTOCOL_GUID_STRING "{8226E96A-B578-4c28-B686-7EC92BAF1EE7}"

    In SMTPFltr.cpp, add the following code to your filter registration code:

    // This function is used to register an application filter
static HRESULT RegisterFWXFilter (BOOL fRegister, FwxScope Scope)
{
    HRESULT hr;
    MSFPCCOM::IFPCFilterProtocolPtr comptrIFPCFilterProtocol;
    CComPtr<IFWXFilterAdmin> pIFWXFilterAdmin;

    hr = CoCreateInstance (CLSID_FWXFilterAdmin,
                  NULL,
                  CLSCTX_SERVER,
                  IID_IFWXFilterAdmin,
                  (LPVOID *) &pIFWXFilterAdmin);
    if (FAILED(hr))
        return hr;

    if (fRegister)
    {
        //Strings should be Unicode in this call
        hr = pIFWXFilterAdmin->
        InstallFilter (CLSID_SMTPFilter,// GUID

                      L"SMTPFilter",// Name
                      L"Screen SMTP messages",// Description
                      L"Microsoft",// Vendor
                      L"1.0",// Version
                      NULL,//Reserved parameter, must be NULL
                      Scope);
        //OK if already installed.
        if (hr == HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
            hr = S_OK;

        if (FAILED(hr))
            return hr;

        hr = pIFWXFilterAdmin
             ->RegisterProtocolForFilter(CLSID_SMTPFilter,
                                         FILTER_PROTOCOL_GUID,
                                         L"SMTP server",
                                         L"SMTP inbound via SMTPFLTR",
                                         NULL,//Reserved parameter, must be NULL
                                         Scope);

        // Returns OK if already installed.
        if (hr == HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
            hr = S_OK;

        if (FAILED(hr))
            return hr;

        //Get a pointer to the protocol just registered
        hr = pIFWXFilterAdmin->GetProtocol(CLSID_SMTPFilter,
                                    FILTER_PROTOCOL_GUID,
                                    Scope,
                                    (struct IFPCFilterProtocol **)&comptrIFPCFilterProtocol);

        if (FAILED(hr))
            return hr;

        try
        {

            //Add primary connection to the protocol just created
            comptrIFPCFilterProtocol->PrimaryConnections->AddTCP(MSFPCCOM::fpcInbound,
                                            25,
                                            25);

            comptrIFPCFilterProtocol->PrimaryConnections->Save();
        }
        catch(_com_error& err)
        {
            //If adding a primary connection to the protocol fails, it is not considered an error
            if(err.Error() != HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
                return err.Error();
        }

    }
    else
    {
        //Unregister protocol
        hr = pIFWXFilterAdmin->UnregisterProtocolForFilter(CLSID_SMTPFilter,
                                                           FILTER_PROTOCOL_GUID,
                                                           Scope);
        //Unregister filter
        hr = pIFWXFilterAdmin->UninstallFilter (CLSID_SMTPFilter, Scope);

    }

    return hr;
}
//////////
// DllInstall - Application filter installation
STDAPI
DllInstall(
    BOOL bInstall,
    LPCWSTR pszCmdLine
)
{
    FwxScope Scope;
    // Must have command line, must be either enterprise or array
    if (!pszCmdLine) return E_INVALIDARG;
    if (wcscmp(pszCmdLine, L"enterprise") == 0) {
        Scope = fwx_EnterpriseScope;
    } else if (wcscmp(pszCmdLine, L"array") == 0) {
        Scope = fwx_ArrayScope;
    } else {
        return E_INVALIDARG;
    }

    return RegisterFWXFilter(bInstall, Scope);
}
  4. Add the following code to smtpfltr.def:
    DllInstall          @5 PRIVATE
  5. In the implementation of IFWXSessionFilter::FirewallEventHandler in FWXSessionFilter.cpp, add the code shown in bold to set the connection protocol as the filter protocol:
    HRESULT STDMETHODCALLTYPE CFWXSessionFilter::FirewallEventHandler(
    /* [out][in] */ const FwxFirewallEvent __RPC_FAR *pFirewallEvent)
{
    HRESULT hr = S_OK;
    IFWXConnection  *piConnection;

    switch (pFirewallEvent->EventType)
    {
    // Bind request for TCP sockets
    case fwx_Bind_Tcp:
        OutputDebugString ("IFWXSessionFilter::FirewallEventHandler –        fwx_Bind_Tcp\n");
        OutputDebugString (FilterAccessString(
                           pFirewallEvent->
                           Parameters.Bind.FilterAccess));

        //Get a pointer to the connection
        piConnection=pFirewallEvent->Parameters.Bind.piConnection;

        //Set the protocol of this connection to be the filter
        //protocol
        hr = piConnection->SetProtocol(FILTER_PROTOCOL_GUID,0);

        if (FAILED(hr))
        {
            OutputDebugString("\tFail to set protocol of connection to  SMTP filter protocol\n");
            return hr;
        }

        break;
  6. Build the project (Rebuild All).

To test the registration and installation code, follow the setup procedures described in Filter Setup, as appropriate for an enterprise or array installation. You will need to reinstall the filter when you complete the filter creation procedure.

Note Filter objects are created when the Firewall service is loaded, so the service must be restarted when you add a new filter or a new version of an existing filter.


Add SMTP Content Filtering Using the IFWXDataFilter Interface

The data filter in this example looks for a string (configurable) in the SMTP message. The firewall attaches a new instance of the data filter to every inbound TCP connection to Port 25 (monitoring the fwx_AcceptedConnection event on this port).

You will need to take the following steps:

  1. Create a COM Object that Implements the IFWXDataFilter Interface
  2. Add the Definition and Implementation of IFWXDataFilter Methods
  3. Attach the data filter
  4. Implement the IFWXIOCompletion Interface
  5. Implement the _CloseSockets and _GetSockets Functions
  6. Perform Data Pumping


Create a COM Object that Implements the IFWXDataFilter Interface

When you create the data filter object, you will implement the following methods:

  • IFWXDataFilter::SetSockets
  • IFWXDataFilter::Detach

Warning Visual C++ will not create a new ATL object if more than one .idl file is included in your project. Delete all the .idl files except SMTPFLTR.idl from the project, add the ATL object as described, and then replace the .idl files that you removed.

  1. Follow cleanup steps similar to those taken to create the COM object that implemented IFWXSessionFilter. This includes the copying and restoration of files, removal of specific files, and removal of several lines of code. See the topic Create an IFWXSessionFilter COM Object to review the cleanup procedures.
  2. Insert a new ATL object (Object — Simple Object)
    • Short Name — SMTPDataFilter
    • Interface — IFWXDataFilter
    • Attributes:

      Threading Model — Free

      Interface — Custom

      Aggregation — No


Add the Definition and Implementation of IFWXDataFilter Methods

Now add the code to define and implement the IFWXDataFilter methods.

To define and implement the IFWXDataFilter methods

  1. Add the definition of IFWXDataFilter methods:

    Copy the prototypes of the methods of IFWXDataFilter from wspfwext.h and add them to smtpdatafilter.h.

    Add the declaration of the methods to smtpdatafilter.h.

  2. Add the implementation of IFWXDataFilter Methods

    Use wspfwext.h to get the prototypes of the methods of IFWXDataFilter and add them to SMTPDataFilter.cpp with implementation code.

    Start with a simple implementation in SMTPDatafilter.cpp; for example,

    return E_NOTIMPL;


Attach the Data Filter

In this procedure you will attach a data filter in CSessionFilter::FirewallEventHandler.

To attach the data filter

  1. For a data filter to be attached to the session when an fwx_AcceptedConnection event occurs, at the beginning of FWXSessionFilter.cpp, you must add the following code:
    #include "SMTPDataFilter.h"
CComPtr <IFWXDataFilter> spIFWXDataFilter;
  2. In FWXSessionFilter.cpp, in the switch statement of the FirewallEventHandler method, add this code to the fwx_AcceptedConnection case:
    CComObject<CSMTPDataFilter> *pSMTPDataFilter;
//Create an instance of the SMTPDataFilter
hr = CComObject<CSMTPDataFilter>::CreateInstance(&pSMTPDataFilter);
    if (SUCCEEDED(hr))
    {
        pSMTPDataFilter->AddRef();

        hr = pSMTPDataFilter->
QueryInterface(IID_IFWXDataFilter,
             reinterpret_cast<void**>(&spIFWXDataFilter));

pSMTPDataFilter->Release();

        if (FAILED(hr))
        {
            OutputDebugString("\tFail to init DataFilter\n");
            return hr;
        }

        //Attach the data filter to the connection
        piConnection=pFirewallEvent->
Parameters.Accept.piConnectionAccepted;
        hr=piConnection->
AttachDataFilter(spIFWXDataFilter,
             fwx_dfpc_External,
             NULL);
    }
  3. Implement the IFWXDataFilter::SetSockets method.

    For the data filter to create a data pump — moving data between the internal SMTP server and the external server or client — the data filter must keep a reference to the sockets at each end of the connection. Therefore , add the following code to SMTPDataFilter.h:

    private:
    CComPtr<IFWXSocket> m_spExternalSocket;
    CComPtr<IFWXSocket> m_spInternalSocket;

    The Firewall service passes a reference to the external and internal sockets used in this connection and the IFWXDataFilter::SetSockets method starts the data-pumping process. The filter must reserve a reference to these sockets.

    Due to the multithreaded architecture of the Firewall service, access to members must be synchronized. In particular, access to the socket interfaces must be synchronized because they are changed by IFWXDataFilter::Detach (see Step 5, following).

  4. Implement the IFWXDataFilter::SetSockets method.

    In place of the simple implementation code you previously wrote, use the following code in SMTPDataFilter.cpp:

    HRESULT STDMETHODCALLTYPE CSMTPDataFilter::SetSockets(
    /* [in] */ IFWXSocket __RPC_FAR *piInternalSocket,
    /* [in] */ IFWXSocket __RPC_FAR *piExternalSocket,
    /* [in] */ IFWXConnection __RPC_FAR *piConnection,
    /* [unique][in] */ IUnknown __RPC_FAR *punkFilterContext)
    {
        //Keep a reference to the sockets
        Lock();
        m_spExternalSocket = piExternalSocket;
        m_spInternalSocket = piInternalSocket;
        Unlock();

        return S_OK;
    }
  5. Implement the IFWXDataFilter::Detach method.

    The Firewall service calls this method when the data filter is no longer needed. IFWXDataFilter::Detach must release the references to the sockets because they are not valid after this method returns.

    In place of the simple implementation code you previously wrote, use the following code in SMTPDataFilter.cpp:

    HRESULT STDMETHODCALLTYPE CSMTPDataFilter::Detach( void)
    {
        //
        // Dereference sockets.
        //
            Lock();
                m_spExternalSocket = NULL;
                m_spInternalSocket = NULL;
            Unlock();

        return S_OK;
    }
  6. Build the project.


Implement the IFWXIOCompletion Interface

To carry out data pumping, the data filter must use an asynchronous input/output (I/O) method. To do so, the data filter has to implement the IFWXIOCompletion interface. Using this interface, the Firewall service notifies the filter upon completion of an I/O operation.

You will implement the IFWXIOCompletion::CompleteAsyncIO method.

To the CSMTPDataFilter class definition in SmtpDataFilter.h, add inheritance from the IFWXIOCompletion class:

public IFWXIOCompletion

Also, add COM interface support for this interface by adding the following line to the COM map of the CSMTPDataFilter class:

COM_INTERFACE_ENTRY(IFWXIOCompletion)

Copy the prototype of the IOCompletion::CompleteAsyncIO method from wspfwext.h and add it to SMTPDataFilter.h and SMTPDataFilter.cpp (with a simple implementation):

SMTPDataFilter.h:

//IFWXIOCompletion

public:
    HRESULT STDMETHODCALLTYPE CompleteAsyncIO(
            /* [in] */ BOOL fSuccess,
            /* [in] */ DWORD Win32ErrorCode,
            /* [in] */ IFWXIOBuffer __RPC_FAR *pIOBuffer,
            /* [in] */ UserContextType UserData,
            /* [unique][in] */ LPSOCKADDR ExternalAddress,
            /* [in] */ INT ExternalAddressLength) ;

SMTPDataFilter.cpp:

HRESULT STDMETHODCALLTYPE CSMTPDataFilter::CompleteAsyncIO(
        /* [in] */ BOOL fSuccess,
        /* [in] */ DWORD Win32ErrorCode,
        /* [in] */ IFWXIOBuffer __RPC_FAR *pIOBuffer,
        /* [in] */ UserContextType UserData,
        /* [unique][in] */ LPSOCKADDR ExternalAddress,
        /* [in] */ INT ExternalAddressLength)
    {
       return S_OK;
    }

This method is called when an I/O operation is completed. In this method you should implement the logic of your filter. This logic is based on the protocol in which you are working; in this case, the SMTP protocol. To start the data pump, add the code shown in bold to CSMTPDataFilter::SetSockets (in SMTPDataFilter.cpp):

#define SOURCE_IS_SERVER 0
#define SOURCE_IS_CLIENT 1
HRESULT STDMETHODCALLTYPE CSMTPDataFilter::SetSockets(
    /* [in] */ IFWXSocket __RPC_FAR *piInternalSocket,
    /* [in] */ IFWXSocket __RPC_FAR *piExternalSocket,
    /* [in] */ IFWXConnection __RPC_FAR *piConnection,
    /* [unique][in] */ IUnknown __RPC_FAR *punkFilterContext)

    {
        //Keep a reference to the sockets
        Lock();
        m_spExternalSocket = piExternalSocket;
        m_spInternalSocket = piInternalSocket;
        Unlock();
    //SOURCE_IS_SERVER and SOURCE_IS_CLIENT are used
    //to differentiate between recv on external and internal sockets
    piInternalSocket ->Recv(NULL,this, SOURCE_IS_SERVER);
    piExternalSocket ->Recv(NULL,this, SOURCE_IS_CLIENT);
        return S_OK;
    }


Implement _CloseSockets and _GetSockets Functions

The function _CloseSockets is used by the data pump in the step Perform Data Pumping; _CloseSockets requires the function _GetSockets.

Implement _CloseSockets in SMTPDataFilter.cpp:

void CSMTPDataFilter::_CloseSockets(BOOL fAbortive)
    {
        CComPtr <IFWXSocket> spExternalSocket;
        CComPtr <IFWXSocket> spInternalSocket;

        OutputDebugString("\tCSMTPDataFilter::_CloseSockets\n");

        _GetSockets(&spInternalSocket,&spExternalSocket);

        if (spInternalSocket)
                    spInternalSocket->Close(fAbortive);

        spInternalSocket.Release();

        if (spExternalSocket)
                    spExternalSocket->Close(fAbortive);

        spExternalSocket.Release();
    }

Add the definition of the _CloseSockets function

void CSMTPDataFilter::_CloseSockets(BOOL fAbortive);

to the header file SMTPDataFilter.h in the private portion of the CSMTPDataFilter class.

Add the function _GetSockets to SMTPDataFilter.cpp:

    void CSMTPDataFilter::_GetSockets(IFWXSocket **ppInternalSocket,
                    IFWXSocket **ppExternalSocket)
    {
            Lock();

            //Get internal socket
           *ppInternalSocket= m_spInternalSocket;
            if (*ppInternalSocket)
        (*ppInternalSocket)->AddRef();

            //Get external socket
           *ppExternalSocket= m_spExternalSocket;
            if (*ppExternalSocket)
        (*ppExternalSocket)->AddRef();

            Unlock();
    }

Add the definition of the _GetSockets function

void CSMTPDataFilter::_GetSockets(IFWXSocket **ppInternalSocket,
                    IFWXSocket **ppExternalSocket);

to the header file SMTPDataFilter.h in the private portion of the CSMTPDataFilter class.


Perform Data Pumping

This example uses a simple data pump that moves data between the server and the client. The actual SMTP filter code uses more sophisticated data pumping and filtering. See SMTPFLTR for more information.

The _CloseSockets function defined in the stepImplement _CloseSockets and _GetSockets Functions is used here.

Add the following code in SMTPDataFilter.cpp in place of the simple implementation of CSMTPDataFilter::CompleteAsyncIO, then build the project:

HRESULT STDMETHODCALLTYPE CSMTPDataFilter::CompleteAsyncIO(
    BOOL      fSuccess,
    DWORD     Win32ErrorCode,
    IFWXIOBuffer *pIOBuffer,
    UserContextType     UserData,
    LPSOCKADDR ExternalAddress,
    INT ExternalAddressLength
    )
{
    DWORD DataLength = 0;
    char *pchCurrent;

    //If the buffer exists, get a reference to it and get its size
    if (pIOBuffer)
        pIOBuffer->GetBufferAndSize((PBYTE*)&pchCurrent, &DataLength);

    //No data was sent, close the sockets
    if (DataLength == 0 || !fSuccess)
    {
        _CloseSockets(!fSuccess);
        return S_OK;
    }

    Lock();
    CComPtr<IFWXSocket>    spExternalSocket = m_spExternalSocket;
    CComPtr<IFWXSocket>    spInternalSocket = m_spInternalSocket;
    Unlock();

    if (UserData==SOURCE_IS_SERVER)
    {
        //Source of the data is the server; filter needs to send
        //it to the external client
        spExternalSocket->Send(pIOBuffer,NULL,0);
        //Read from internal SMTP server
        spInternalSocket ->Recv(NULL,this,SOURCE_IS_SERVER);
    }
    else
    {
        //Source of the data is the client, filter needs to send
        //it to the server
        spInternalSocket ->Send(pIOBuffer,NULL,0);

        //Read from client
        spExternalSocket ->Recv(NULL,this,SOURCE_IS_CLIENT);
    }
return S_OK;
}


Reading Configuration from Vendor Parameter Sets

To make the filter configurable with respect to changing the string it seeks, you need storage that the filter and the administrator can access to read and write configuration data. This kind of storage is provided by ISA administration COM objects — specifically, the FPCVendorParametersSet object. When you use FPCVendorParametersSet, configuration backup and restore operations are done automatically, together with the rest of the ISA configuration operations. FPCVendorParametersSet also allows for configuration data to be shared across an ISA Server array.

To read configuration data from vendor parameter sets

  1. Add the public method Initialize to the CSMTPDataFilter class in SMTPDataFilter.h. This method allows information to be passed to the data filter object.
        HRESULT Initialize(CComPtr<IFWXFirewall> pCallback);

    This initialization method would be called by the CFWXSessionFilter::FwxFirewallEventHandler method.

  2. Add a private member to CSMTPDataFilter class in SMTPDataFilter.h:
    char *m_StringToLookFor;
  3. Add the following implementation code to SMTPDataFilter.cpp:
    HRESULT CSMTPDataFilter::Initialize(CComPtr<IFWXFirewall> pCallback)
{

    HRESULT hr=S_OK;
    _bstr_t Value;  //Value from ISA storage
    CComPtr<IFWXFilterAdmin> pIFWXFilterAdmin;
    MSFPCCOM::IFPCVendorParametersSetPtr comptrIFPCVendorParametersSet;
    struct IFPCVendorParametersSet * pIFPCVendorParametersSet;

    hr = CoCreateInstance (CLSID_FWXFilterAdmin,
                           NULL,
                           CLSCTX_SERVER,
                           IID_IFWXFilterAdmin,
                           (LPVOID *) &pIFWXFilterAdmin);
    if (FAILED(hr))
        return hr;

    hr =pIFWXFilterAdmin->GetFilterParameterSet(CLSID_SMTPFilter, fwx_DefaultScope, &pIFPCVendorParametersSet);
    if (FAILED(hr))
        return hr;

    comptrIFPCVendorParametersSet.Attach((MSFPCCOM::IFPCVendorParametersSet*) pIFPCVendorParametersSet, true);

    try
    {
        //Read the string to find
        Value=comptrIFPCVendorParametersSet->Value[_bstr_t("StringValue")];
        m_StringToLookFor =new char [strlen(Value)+1];
        if (m_StringToLookFor ==NULL)
            return E_OUTOFMEMORY;
        strcpy(m_StringToLookFor,Value);
    }
    catch(_com_error& /*err*/)
    {
        //Set default value to m_StringToLookFor
        m_StringToLookFor = new char[12];
        strcpy(m_StringToLookFor,"Virus Virus");
    }
    return  S_OK;
}
  4. In SMTPDataFilter.h, add the following code to the constructor of the class CSMTPDataFilter:
    m_StringToLookFor = NULL;

    and add the following destructor of class CSMTPDataFilter:

        ~CSMTPDataFilter()
    {
        delete [] m_StringToLookFor;
    }


Raising an Event When a String is Found

To inform the system administrator that it found a message containing a string it was seeking, the filter must use an event-raising mechanism. This requires the filter to define an event and make the event available to the administrator through the filter registration process. This event should not be confused with a firewall event. For information on alerts, see Adding a Custom Event and Alert.

The filter must define an alert event, which it will signal whenever a string is found.

Definition of the event should take place during registration of the filter with the Firewall service because you want the administrator to be able to define alerts using this event. When the filter is unregistered, it should remove this event definition. However, the alert for the event should be removed first, or the event removal will fail. If the event is not removed, then when the filter is re-registered, you will receive an error for attempting to create a file that already exists.

To create an alert event

  1. Register alert events in ISA by adding the following code to SMTPFLTR.cpp:
    #define FILTER_EVENT_NAME_STRING "SMTP Filter Event"
#define FILTER_EVENT_DESCRIPTION_STRING "SMTP Filter Event"

    Add the code shown in bold to the function RegisterFWXFilter in SMTPFLTR.cpp:

    MSFPCCOM::IFPCFilterProtocolPtr comptrIFPCFilterProtocol;
MSFPCCOM::IFPCPtr comptrIFPC;
MSFPCCOM::IFPCEventDefinitionPtr  comptrIFPCEventDefinition;
//Create an instance of ISA admin object
comptrIFPC.CreateInstance(MSFPCCOM::CLSID_FPC);

    CComPtr<IFWXFilterAdmin> pIFWXFilterAdmin;

    hr = CoCreateInstance (CLSID_FWXFilterAdmin,
                  NULL,
                  CLSCTX_SERVER,
                  IID_IFWXFilterAdmin,
                  (LPVOID *) &pIFWXFilterAdmin);
    if (FAILED(hr))
        return hr;

    //Create an instance of the ISA admin object. The Scope parameter is used to select the right object:
    //For enterprise scope, use CLSID_FPCDS; otherwise use CLSID_FPC.
    hr = comptrIFPC.CreateInstance((Scope == fwx_EnterpriseScope) ? MSFPCCOM::CLSID_FPCDS : MSFPCCOM::CLSID_FPC);
    if (FAILED(hr))
        return hr;

    The following code shown in bold should be added to the registration code in the try-catch block:

    try
{
//Create a new event for this filter. The reason this
//code is inside a try-catch block is that if this event
//already exists, an exception will be raised
comptrIFPCEventDefinition =
    comptrIFPC->Arrays->GetContainingArray()->PolicyElements->EventDefinitions->Add(FILTER_EVENT_DESCRIPTION_STRING,_bstr_t(FILTER_GUID_STRING),NULL);
comptrIFPCEventDefinition->Description = FILTER_EVENT_DESCRIPTION_STRING;
comptrIFPCEventDefinition->Name = FILTER_EVENT_NAME_STRING;
comptrIFPCEventDefinition->Save();
}
catch(_com_error& err)
{
    //If the event already exists, it is not considered an error
    if(err.Error() != HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
        return err.Error();
}

    The following should be added to the unregistration code of the RegisterFWXFilter function:

    //Remove the event
comptrIFPC->Arrays->GetContainingArray()->PolicyElements->EventDefinitions->Remove(FILTER_GUID_STRING);
//Save the change
comptrIFPC->Arrays->GetContainingArray()->PolicyElements->EventDefinitions->Save();
  2. Create an alert that uses the SMTP event

    See the ISA product documentation for help in creating a new alert.

  3. Signal event when the string is found

    To raise an event the filter must use the alert service API.

    1. Add the file alertsrv.idl to the project; then add the following code to Stdafx.h:
      #import "alertsrv.tlb" rename_namespace("ALERTSRVLib") named_guids
    2. Add a private member to CSMTPDataFilter class in SMTPDataFilter.h:
      ALERTSRVLib::IFpcAlertNotificationPtr m_comptrIFPCAlertNotification;
    3. Add the following code to the CSMTPDataFilter::Initialize function in SMTPDataFilter.cpp:
      hr=m_comptrIFPCAlertNotification.CreateInstance(ALERTSRVLib::CLSID_FpcAlertNotification);

    Now the filter can call the IFPCAlertNotification::SignalEvent method of this object to signal when the event occurs.

  4. Build the project.
  5. Follow the Filter Setup procedure to install the filter.


SMTPFLTR Test Environment

The purpose of the SMTPFLTR filter is to screen incoming Simple Mail Transfer Protocol (SMTP) messages. The filter looks for a specified string in the data section of an e-mail message. If the string is found, the filter signals an ISA event. In addition, it adds a text string to the beginning of the Subject: line in the e-mail message.

Both strings are read from the FPCVendorParametersSet object, making them configurable by the ISA administrator.

This document shows how to test the filter in two real-life scenarios:

  • Incoming SMTP message from an external SMTP client.
  • Incoming SMTP message from an external SMTP server (which is forwarding a request from a different SMTP client).

More information on the SMTP protocol definitions can be found in RFC 821 and RFC 1830.

Note The procedures presented here refer to the use of a Microsoft mail server. If you are using a different mail server, refer to its accompanying documentation for configuration information.

Shell commands provided in this example are for demonstration purposes and can vary from system to system.


Lab Configuration for SMTPFLTR

This section contains the following topics:

  • ISA Server
  • Internal SMTP Server
  • External SMTP Server


ISA Server

The first step to setting up a test environment is to set up ISA Server correctly.

  1. Install Windows 2000 Server.
  2. Install ISA Server.
  3. In the Access Policy|Protocol Rules node of the ISA Console Tree, right-click to select New|Rule,. The Protocol Rule Creation Wizard starts. In the wizard, make the following selections:
    • Rule action — select Allow.
    • Protocols — select Selected protocols. Then select the appropriate protocol from the list. In the case of the SMTP filter, select SMTP Server.
    • Schedule — Always (default).
    • Client Type — Any request (default).
  4. Stop SMTP service on the ISA computer at the command prompt by typing:
    net stop "Microsoft SMTP Service"


Internal SMTP Server

Set up an internal SMTP server to work with ISA Server.

  1. Install SMTP server.

    Microsoft SMTP server comes with Internet Information Services (IIS) 5.0, which is part of the default installation of Windows 2000 Server.

  2. Install ISA client on the SMTP server. Because the SMTP server is behind the ISA server, it functions as a client in this scenario.

    Use the MSEClnt installation share on the ISA server.

  3. Set up the SMTP server to work behind ISA server.

    Add a text file called wspcfg.ini, with the following content, to the winnt\system32\inetsrv directory, and then restart IIS:

    [inetinfo]
ServerBindTcpPorts=25
KillOldSession=1
Persistent=1
  4. Restart the SMTP service.
  5. Notice that inetinfo.exe hosts many services. You must stop each service before inetinfo.exe terminates. If you are using SMTP service, you can use the following shell commands:
    net stop "World Wide Web Publishing Service"
net stop "FTP publishing service
net stop "Simple Mail Transport Protocol (SMTP)"
net stop "IIS Admin Service"
net start "Microsoft SMTP Service"

    Note When you switch from a Firewall client test configuration to a SecureNAT client test configuration, or from a SecureNAT client to a Firewall client, the Firewall service and the SMTP service must be stopped and restarted.


External SMTP Server

Set up an external SMTP server to work with ISA Server.

  1. Install SMTP server.
  2. Configure the SMTP service to forward messages:
    • Add new remote domain.
    • Open properties dialog of the new domain.
    • Select the Allow incoming mail to be relayed check box.
    • Select the Forward all mail to smart host option and type the external name or IP address of the ISA server. Alternatively, use the Smart host setting on the Delivery Property page of SMTP server properties.


Verification

To make certain the SMTPFLTR test environment is set up correctly, you should verify the connection.

  1. Open the telnet application on the external computer and connect to the ISA server on Port 25.
  2. You should receive a message similar to the following:
    "220 <YourInternalServerName> Microsoft ESMTP MAIL Service, Version: 5.0.2054.0054.0 ready at Mon, 28 Jun 1999 14:10:48 +0300"

This message indicates that the internal SMTP server is available and can be accessed from the external network through ISA. Notice that the server name in this message is that of the internal server, not the ISA server.

If you get an error message, try restarting the Firewall service and then restarting the internal SMTP service.


Sample Filters

Sample application filters developed by using the ISA Server SDK are provided in the Samples\application_filters directory on the ISA CD-ROM in the SDK directory. These are provided to demonstrate coding techniques for creating application filters. The samples are briefly described in the following text. For more information regarding each filter, see the ReadMe file provided with each sample.

Note to C++ Programmers The samples work only if compiled using Visual C++ 6.0 (Service Pack 3 or higher) with Active Template Library (ATL) 3.0.

CL.EXE, LINK.EXE, and other command-line tools require you to set certain environment variables properly. These include PATH, which must point to the \bin subdirectory of your Visual C++ installation, LIB, which must point to \lib, and INCLUDE, which must point to \include.

When you install Visual C++, Setup creates a batch file, VCVARS32.BAT, that contains commands to modify the PATH, LIB, and INCLUDE environment variables. If these variables haven't been set properly, run VCVARS32.BAT before you compile at the command prompt. VCVARS32.BAT is located in the \bin subdirectory. Note that you do not need to run VCVARS32.BAT if you are compiling your program inside the development environment.

For more information, see MSDN.

In addition to the samples, several filters are provided as part of ISA. These application filters may also be of interest to filter developers. The filters include:

  • An FTP filter that works with Firewall service and SecureNAT clients.
  • An H.323 protocol filter that works with Firewall service and SecureNAT clients.
  • An HTTP Redirector filter.
  • A streaming media filter.
  • An SMTP filter.
  • An RPC filter.
  • A SOCKS 4.3 filter.

For a general understanding of the filter development process, see Developing Application Filters. For a detailed example of the filter-development procedure, see How to Create an Application Filter.


Connector

The Connector sample is a console application that emulates an application protocol with a primary connection for control and secondary connections for data. The secondary connections can be inbound or outbound and use either UDP or TCP.

The Connector application implements both the client and the server side of the protocol.

The related sample filter ConnectorFilter demonstrates how to enable this type of protocol to pass through the Firewall service for Firewall service clients and SecureNAT clients.

An illustration showing the logic of the Connector and ConnectorFilter samples is provided in ConnectorFilter.


ConnectorFilter

The ConnectorFilter sample filter enables a complex protocol that requires secondary connections on random ports.

The ConnectorFilter sample filter allows the Connector sample to work with SecureNAT clients and Firewall clients.

This figure illustrates the logic of the Connector and ConnectorFilter sample filters.

Methods Used in ConnectorFilter Sample

The ConnectorFilter sample uses the following methods:

IFWXConnection::AttachDataFilter

IFWXConnection::GetExternalSocketName

IFWXIOBuffer::Append

IFWXIOBuffer::GetBufferAndSize

IFWXIOCompletion::CompleteAsyncIO

IFWXFirewallAction::Cancel

IFWXSession::AllowFutureConnect

IFWXSession::BindForClient

IFWXSession::GetSessionFlags

IFWXSession::RetroactiveAllowBind

IFWXSessionFilter::Detach

IFWXSessionFilter::FirewallEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::GetProtocol

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXFirewall::CreateBuffer

IFWXFirewall::DuplicateFilterHookEvents

See Also

Connector


DbgDump

The DbgDump sample filter registers for notifications on all possible events and installs data filters on all connections. The filter outputs information about the events to the debugger.

To view the output, attach a debugger to the fwsrv.exe process. You can also view the output by using the DBWIN or DBMON utilities.

Note that because the filter dumps each buffer to the debugger, the Firewall service will experience a considerable slow down and may experience time-outs, even under a moderate load.

Methods Used in DbgDump Sample

The DbgDump sample uses the following methods:

IFWXConnection::AttachDataFilter

IFWXIOBuffer::GetBufferAndSize

IFWXIOCompletion::CompleteAsyncIO

IFWXSession::GetClientAddress

IFWXSession::GetClientMachineName

IFWXSessionFilter::Detach

IFWXSessionFilter::FirewallEventHandler

IFWXSocket::Recv

IFWXSocket::Send

IFWXSocket::SendTo

IFWXSocket::Shutdown

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::UninstallFilter

IFWXFirewall::DuplicateFilterHookEvents


ExeBlock

The ExeBlock sample filter demonstrates the use of data filters and hooking into the Firewall service thread pool. The filter hooks into FTP control channel (TCP port 21). The data filter (CEBFTPDataFilter) records PORT and PASV commands, and calls the IFWXSession::SetDataFilterFactory method.

When a new secondary connection is made, or accepted, the COM object ClassFactory creates a data filter (CEBScannerDataFilter) to be attached by the Firewall service. The filter scans the incoming file.

This sample blocks all executable files (any file that begins with MZ or ZM) unless a protocol rule is defined that allows a specific user to receive executable files. The user must be defined by an Internet Protocol (IP) address in the case of a SecureNAT client, and by user name in the case of a Firewall client.

The protocol rule must be added to the Protocol Rules in the ISA console.

The scanner data filter creates a temporary file, and downloads the whole file. It then scans the file, and if the file passes, it is transferred to the internal client.

Limitations:

  • The sample does not handle file uploads.
  • The sample does not handle transfer mode different than stream.
  • The sample does not handle structures other than file.

Methods Used in ExeBlock Sample

The ExeBlock sample uses the following methods:

IFWXConnection::AttachDataFilter

IFWXConnection::Deny

IFWXExternalIOCompletion::CompleteAsyncIO

IFWXIOBuffer::Append

IFWXIOBuffer::GetBufferAndSize

IFWXIOBuffer::SetDataSize

IFWXIOCompletion::CompleteAsyncIO

IFWXOverlapped::GetOverlapped

IFWXOverlapped::SetNotificationInterface

IFWXSession::AccessCheck

IFWXSession::SetDataFilterFactory

IFWXSessionFilter::Detach

IFWXSessionFilter::FirewallEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXFirewall::CreateBuffer

IFWXFirewall::CreateConstBuffer

IFWXFirewall::CreateOverlapped

IFWXFirewall::DuplicateFilterHookEvents

IFWXFirewall::HookToCompletionPort


ServerSplit

The ServerSplit sample filter demonstrates the use of connection emulation for inbound connections.

The filter begins by binding a socket for TCP Port 3333, and then it waits for connections on this port. When a Firewall client requests to bind Port 3333 on the Firewall service, the filter intercepts the request, and requests to emulate the connection. That is, the service does not attempt to bind a socket to that port in response to that specific client request because such an attempt would fail if more than one client tries to bind to the same port. Instead, the service reports a successful bind to the client. The filter then manages the multiplexing of incoming connections on the socket that was already bound by the filter.

This technique allows internal servers behind the Firewall service to share listening ports and receive incoming connections from external clients.When a connection arrives to the Firewall service on Port 3333 the service notifies the filter by calling the IFWXAcceptCompletion::CompleteAsyncAccept method. The filter then checks its list of emulated connections. If the list is empty, it sends a short message and terminates the connection. Otherwise, it takes the first connection on the list and calls IFWXConnection::EmulateConnection. The class CDataPump provides the data-pump for this connection. That connection is then moved to the end of the queue.

The following illustration summarizes the process followed by the ServerSplit sample.

Note When the external client disconnects, a fwx_ConnectionTerminating event arrives for the accepted connection, but not for the listening connection, if an appropriate ServerBindTcpPorts entry is specified in wspcfg.ini.

Methods Used in ServerSplit Sample

The ServerSplit sample uses the following methods:

IFWXConnection::Deny

IFWXConnection::EmulateConnection

IFWXConnection::SetProtocol

IFWXConnection::SetSocketName

IFWXIOBuffer::GetBufferAndSize

IFWXNetworkSocket::Accept

IFWXNetworkSocket::Bind

IFWXNetworkSocket::Listen

IFWXSessionFilter::FirewallEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXSocket::SendTo

IFWXSocket::Shutdown

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXFirewall::CreateConstBuffer

IFWXFirewall::CreateNetworkSocket

IFWXFirewall::DuplicateFilterHookEvents


SMTPFLTR

The SMTPFLTR sample filter captures and analyzes data sent by external clients using the SMTP protocol. The Firewall service attaches a new instance of the data filter to every inbound port 25 TCP session. The filter can be configured to look for a particular string in the SMTP message.

SMTPFLTR extends the firewall so that it secures SecureNAT clients, which do not have the Firewall client installed.

Note In a SecureNAT scenario, IFWXFilter::AttachToSession and IFWXSessionFilter::FirewallEventHandler are not called, due to this filter's use of a class factory to create data filters.

SMTPFLTR is the example used in How to Create an Application Filter.

SMTPFLTR also creates a property sheet for the application filter, to extend the Microsoft Management Console (MMC). This procedure is described in How to Create a Microsoft Management Console Snap-in.

Methods Used in SMTPFLTR Sample

The SMTPFLTR sample uses the following methods:

IFWXConnection::SetProtocol

IFWXIOBuffer::GetBufferAndSize

IFWXIOCompletion::CompleteAsyncIO

IFWXSession::BindForClient

IFWXSessionFilter::Detach

IFWXSessionFilter::FirewallEventHandler

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXDataFilter::Detach

IFWXDataFilter::SetSockets

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::GetFilterParameterSet

IFWXFilterAdmin::GetProtocol

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::RegisterProtocolForFilter

IFWXFilterAdmin::UninstallFilter

IFWXFilterAdmin::UnregisterProtocolForFilter

IFWXFirewall::DuplicateFilterHookEvents

IFWXFirewall::GetNATSession


SOCKS Sample Filters

Two SOCKS protocol filter samples are provided with the ISA SDK. One works with the SOCKS 4/4a protocol, and the other with the SOCKS 5 protocol.


SOCKS 4/4a Sample Filter

This sample application filter demonstrates the use of SOCKS protocol version 4/4a. The filter hooks into the SOCKS control channel (TCP port 1080). For each connection made to this port, an object (CSocksConnection) is created. This object identifies calls to IFWXNetworkSocket::Connect and IFWXNetworkSocket::Bind and handles them.

When the CSocksConnection object detects a call to IFWXNetworkSocket::Connect, the filter creates a session for the client's IP address if it is needed; that is, if there is no session already connected to that IP address. The filter then creates a socket on this session and makes a connection to the destination address that was provided by the client in the IFWXNetworkSocket::Connect request.

When the Firewall service detects a call to IFWXNetworkSocket::Bind, the filter searches for the related session. This session should exist because IFWXNetworkSocket::Bind always comes after IFWXNetworkSocket::Connect.

If this session does not exist, the filter sends an error packet to the client. If the session does exist, the filter creates a socket and calls IFWXNetworkSocket::Bind, IFWXNetworkSocket::Listen, and IFWXNetworkSocket::Accept for the client. The filter then sends a reply to the client with the external address of the proxy server to which the external server should connect.

After accepting the connection from the server, the filter sends the client a second packet containing the internal address to which the client should send the data.

If the client sends a domain name rather than an IP address in one of these commands, a name resolution is performed by the SOCKS filter.

The sample only handles SOCKS 4/4a.

Methods Used in SOCKS 4/4a Sample Filter

The SOCKS 4/4a sample uses the following methods:

IFWXIOBuffer::GetBufferAndSize

IFWXNetworkSocket::Accept

IFWXNetworkSocket::Bind

IFWXNetworkSocket::Connect

IFWXNetworkSocket::GetPeerName

IFWXNetworkSocket::GetSockName

IFWXNetworkSocket::Listen

IFWXNetworkSocket::SetPacketFilterOptions

IFWXSession::CreateNetworkSocket

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::UninstallFilter

IFWXFirewall::CreateBuffer

IFWXFirewall::CreateNetworkSocket

IFWXFirewall::CreatePrivateSession

IFWXFirewall::DuplicateFilterHookEvents

IFWXFirewall::EndHeavyBlockingOperation

IFWXFirewall::IsInternal

IFWXFirewall::StartHeavyBlockingOperation


SOCKS 5 Sample Filter

This sample application filter demonstrates the use of the SOCKS 5 protocol.The filter hooks into the SOCKS control channel (TCP port 1080). For each connection made to this port, an object (CSocksConnection) is created. This object identifies calls to IFWXNetworkSocket::Connect and IFWXNetworkSocket::Bind and handles them.

First, there is a negotiation between the client and the SOCKS filter, which is acting as a SOCKS server. In the negotiation the client offers the server ways to authenticate the client. The server picks one way (in this sample, user name and password) and then the client sends the server a user name and password. The server checks the authentication and if this user is allowed to make a connection, the SOCKS protocol continues as in the SOCKS 4/4a protocol.

When the CSocksConnection object detects a call to IFWXNetworkSocket::Connect, the filter creates a session for the client's IP address if it is needed; that is, if there is no session already connected to that IP address. The filter then creates a socket on this session and makes a connection to the destination address that was provided by the client in the IFWXNetworkSocket::Connect request.

When the Firewall service detects a call to IFWXNetworkSocket::Bind, the filter searches for the related session. This session should exist because IFWXNetworkSocket::Bind always comes after IFWXNetworkSocket::Connect.

If this session does not exist, the filter sends an error packet to the client. If the session does exist, the filter creates a socket and calls IFWXNetworkSocket::Bind, IFWXNetworkSocket::Listen, and IFWXNetworkSocket::Accept for the client. The filter then sends a reply to the client with the external address of the proxy server to which the external server should connect.

After accepting the connection from the server, the filter sends the client a second packet with the internal address to which the client should send the data.

If, in one of these commands, the client sends a domain name instead of an IP address, a name resolution is performed by the SOCKS filter.

The sample only handles SOCKS 5.

Methods Used in SOCKS 5 Sample Filter

The SOCKS 5 sample uses the following methods:

IFWXImpersonator::Impersonate

IFWXImpersonator::RevertToSelf

IFWXIOBuffer::GetBufferAndSize

IFWXNetworkSocket::Accept

IFWXNetworkSocket::Bind

IFWXNetworkSocket::Connect

IFWXNetworkSocket::GetPeerName

IFWXNetworkSocket::GetSockName

IFWXNetworkSocket::Listen

IFWXNetworkSocket::SetPacketFilterOptions

IFWXSession::CreateNetworkSocket

IFWXSocket::Close

IFWXSocket::Recv

IFWXSocket::Send

IFWXFilter::AttachToSession

IFWXFilter::FilterInit

IFWXFilter::FilterShutdown

IFWXFilterAdmin::InstallFilter

IFWXFilterAdmin::UninstallFilter

IFWXFirewall::CreateBuffer

IFWXFirewall::CreateNetworkSocket

IFWXFirewall::CreatePrivateSession

IFWXFirewall::DuplicateFilterHookEvents

IFWXFirewall::EndHeavyBlockingOperation

IFWXFirewall::IsInternal

IFWXFirewall::StartHeavyBlockingOperation


Developing Web (ISAPI) Filters for ISA

Web (ISAPI) filters detect and process HTTP events. Internet Security and Acceleration (ISA) Server 2000 supports ISAPI filter development and implementation, previously available only with Internet Information Services (IIS). ISA Server operates independently of IIS, while using the definition of ISAPI functions and structures provided in the Windows 2000 Software Development Kit (SDK). This topic provides information about ISAPI filters, as implemented in ISA.

In ISA Management and in the product documentation, ISAPI filters are referred to as Web filters.

For other general information regarding ISAPI filter development, see MSDN.

Note to Developers of Web filters for Internet Information Services

There are several differences between implementation of ISAPI in IIS and in ISA. These are described in ISAPI: Comparing IIS and ISA.

This section contains the following topics:

  • Introduction to Web Filters
  • Web Filter Development Tools
  • Web Filter Administration
  • Registration
  • Web Filter Samples
  • Pass-Through Authentication
  • ISAPI: Comparing IIS and ISA


Introduction to Web Filters

Web (ISAPI) filters allow you to intervene in the processing of HTTP requests. Web filters are dynamic-link libraries (DLLs) that are loaded when the ISA Web proxy (w3proxy) service is started and stay in memory until the service shuts down. Web filters can be configured to receive filter-event notifications that occur with each HTTP request that the ISA Web proxy service receives and with each response returned through the Web proxy by an external Web server.

The following illustration provides a schematic overview of the HTTP request-and-response process. A Web filter can register for and react to the events represented in the illustration.

This section contains the following topics:

  • Uses of Web Filters
  • Web Filter Basics
  • ISA Web Proxy Architecture


Uses of Web Filters

You can use Web (ISAPI) filters to facilitate applications that perform a number of different tasks, including:

  • Custom authentication schemes
  • Compression
  • Encryption
  • Logging
  • Traffic analysis or other request analyses
  • Request scanning and modification
  • Response scanning and modification

The ability to examine and if necessary, modify both incoming and outgoing streams of data makes Web filters very powerful and flexible.


Web Filter Basics

When a Web (ISAPI) filter is loaded, the filter passes a structure to the ISA Web proxy service, which contains, in addition to other information, a bit field that specifies the types of filter events of which the filter should be notified. Each time one of those events occurs, an event notification is sent, and every Web filter that has specified interest in that event is notified.

Designing a Web filter requires you to consider what events your want the filter to react to, and decide what processing the filter will perform when the vent occurs. In addition to those basic design considerations, you have to select a priority for the filter, and ensure that it will be properly registered so that it is loaded by the Web proxy service.


ISA Web Proxy Architecture

The ISA Web proxy service is implemented as a separate service called w3proxy. Functions provided by this service include:

  • Configurable network connections for forward and reverse proxy.
  • Parsing of HTTP 1.1 protocol headers.
  • HTTP 1.1 proxy authentication of client requests.
  • Web filter-notification support.

Note to Developers of Web Filters for Internet Information Services

There are several differences between the implementation of ISAPI in Internet Information Services (IIS) and in ISA. These are described in ISAPI: Comparing IIS and ISA.


Web Filter Development Tools

The ISA Server SDK provides the tools you need to develop Web (ISAPI) filters. These are described briefly here and in more detail in the Web Filter Reference. This section includes the following topics:

  • Web Filter Functions
  • Web Proxy Notification Structures
  • Web Proxy Notification Events


Web Filter Functions

Web (ISAPI) filters for the ISA Web proxy service implement the following standard entry functions:

  • GetFilterVersion
  • HttpFilterProc
  • TerminateFilter

These are described here briefly and in greater detail in the Web filter reference.

GetFilterVersion

The GetFilterVersion function is the first entry-point function called by ISA Web proxy on your Web filter, and it must be present for the filter to work. The Web proxy service passes a pointer to a HTTP_FILTER_VERSION data structure, which can be used to supply key filter configuration information to the Web proxy. The most important information passed to the Web proxy is the bitmask that contains flags that specify which notification events your filter can process, and a flag that indicates the overall processing priority for your filter.

HttpFilterProc

Whenever a notification event for which the filter has registered (in GetFilterVersion) occurs, the ISA Web proxy service calls the HttpFilterProc function. The Web proxy uses this function to pass information and control to the Web filter.

TerminateFilter

This function indicates to the filter that it is going to be removed from memory. When this function is called, you should make sure that the filter closes any attachments it has made to system resources.

Note TerminateFilter is an optional function. However, you must provide this function if your filter needs to free any allocated or locked resources before being unloaded.


Web Proxy Notification Structures

Web proxy service of ISA Server works with the notifications described here. Detailed information about the notification structures can be found in the Web filter reference.

HTTP_FILTER_ACCESS_DENIED

This structure contains information about the SF_NOTIFY_ACCESS_DENIED event. The Web proxy service provides a pointer to this structure when the user is presented with an Access Denied error message.

HTTP_FILTER_AUTH_COMPLETE_INFO

This structure contains information about the SF_NOTIFY_AUTH_COMPLETE event. This event is fired after the client identity has been authenticated by the Web proxy service. The structure includes methods that allow you to view or modify the request method, URL, version, or headers sent from the client. The structure also contains a method that retrieves a handle to the token of the authenticated user whom the Web proxy is impersonating.

HTTP_FILTER_AUTHENT

This structure contains information about the SF_NOTIFY_AUTHENTICATION event. The Web proxy service provides a pointer to this structure when it is authenticating a user.

HTTP_FILTER_CONTEXT

This structure is used by HttpFilterProc to obtain information about the current request. The structure includes pointers to the following functions:

  • GetServerVariable
  • AddResponseHeaders
  • WriteClient
  • AllocMem
  • ServerSupportFunction

HTTP_FILTER_LOG

This structure contains information about the SF_NOTIFY_LOG event. The Web proxy service provides a pointer to this structure when it is writing information to a log file.

HTTP_FILTER_PREPROC_HEADERS

This structure contains information about the SF_NOTIFY_PREPROC_HEADERS event. The Web proxy service provides a pointer to this structure when it is preprocessing a request's headers.

HTTP_FILTER_RAW_DATA

This structure contains information about the SF_NOTIFY_READ_RAW_DATA or SF_NOTIFY_SEND_RAW_DATA event. The Web proxy service provides a pointer to this structure when it is reading or sending raw data.

HTTP_FILTER_SEND_RESPONSE

Web filters receive this notification immediately before they send 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.

HTTP_FILTER_URL_MAP

This structure does not apply to ISA Server's implementation of ISAPI.

HTTP_FILTER_VERSION

This structure is used by the GetFilterVersion function to obtain the filter's version information.


Web Proxy Notification Events

There are three types of notification events that your Web (ISAPI) filter can consider:

  • General notifications related to the request.
  • Filter priority notifications.
  • Port security setting notifications.

The notification events are described in the Web filter reference.


Web Filter Administration

In the ISA Web proxy service, setup information is stored in ADSI or the Registry. The COM object FPCWebFilter is provided so that you can access Web filter administration information. The FPCWebFilter object is a member of the FPCWebFilters collection.

Filter information is installed and administered on an array base, so that a Web filter is installed across an array, and not on a single server of the array.

An example of Web filter administration that uses the ISA FPC interfaces is provided in Web Filter Setup.

Use the corresponding COM objects, as shown in Web Filter Setup.


Web Filter Setup

To set up a filter, use the FPCWebFilter and FPCWebFilters COM objects. Each FPCWebFilter object is defined by the globally unique identifier (GUID) used to add it to the FPCWebFilters collection.

To enable installed Web (ISAPI) filters, you need to stop and then restart the ISA Web proxy service.

Provided here are examples showing how to add a filter, change its priority, enable it, disable it, and delete it. Each example includes code for Microsoft® Visual Basic®, and Visual Basic Scripting Edition (VBScript):

  • Adding a New Filter
  • Changing Filter Order
  • Disabling a Filter
  • Enabling a Filter
  • Deleting a Filter

Note You can also write code into a Web filter so that it can be registered and unregistered from the command line, and added to ISA Management. This is described in Self-Registering Web Filters.


Adding a New Filter

You can add a new filter. The following examples show language-specific code for adding a filter.

Visual Basic Example

To add the filter called MyFilter, first add Microsoft Internet Security and Acceleration Server 2000 Administration Library to your Project References, then use the following code:

Dim objFPC As FPC
    Dim objWebFilter As FPCWebFilter
    Dim objWebFilters As FPCWebFilters
    Set objFPC = CreateObject("FPC.Root")
    Dim MyGuid As String
    MyGuid = "{2474E364-FAF1-403f-9AFE-C2A73D667447}"
    Dim RelativePath As String
    RelativePath = "Test\MyFilter\Bin\MyFilter.dll"
    Dim Name As String
    Name = "MyFilter"
    'Add a new Web filter
    Set objWebFilter = objFPC.Arrays.GetContainingArray.Extensions.WebFilters.Add(MyGuid, Name, RelativePath, fpcFilterPriority_High, FpcFilterDirectionBoth)
    objWebFilter.Description = "Filter Description"
    objWebFilter.Name = "Filter Name"
    objWebFilter.Vendor = "Vendor Name"
    objWebFilter.Version = "1.0"
    objFPC.Save

Visual Basic Scripting Edition Example

To add the filter called MyFilter by using a dynamic-link library (DLL) at relative path Test\MyFilter\Bin\MyFilter.dll, open a file and name it FilterAdd.vbs. Then insert in FilterAdd.vbs the following code (where the GUID is any arbitrary GUID that is not yet associated with any other filter):

set FPC = WScript.CreateObject("FPC.Root")
        Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
               Set mfilter = filters.Add("{5b6f6af3-3928-44a3-90f6-c96295c51da6}",
                                         "MyFilter", " Test\MyFilter\Bin\MyFilter.dll ", 2, 2)
        '2 == fpcFilterPriority_High
        mfilter.Description = "Filter Description"
        mfilter.Vendor = "Filter vendor"
        mfilter.Version = "1.0"
        mfilter.Enabled = True
        filters.Save
        WScript.Echo "done"


Changing Filter Order

You can change the filter order as needed.

Visual Basic Example

Use the following Visual Basic code to move the first filter one place lower in the filter order:

Set objWebFilters = objFPC.Arrays.GetContainingArray.Extensions.WebFilters
    objWebFilters.Refresh
    objWebFilters.MoveDown 1
    objWebFilters.Save

Visual Basic Scripting Edition Example

In this example, the first filter becomes the second to be called among filters with the same priority. Create a file called MoveDown.vbs, and then insert the following code:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
filters.MoveDown  1
filters.Save
WScript.Echo "done"


Disabling a Filter

The following examples show how to disable a filter.

Visual Basic Example

Use the following Visual Basic code to disable an ISA Web filter:

Set objWebFilter = objFPC.Arrays.GetContainingArray.Extensions.WebFilters.Item(Guid)
    objWebFilter.Enabled = False
    objWebFilter.Save

Visual Basic Scripting Edition Example

To disable a filter with a known GUID, create a file called Disable.vbs, and then insert the following code:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
Set mfilter = filters("{5b6f6af3-3928-44a3-90f6-c96295c51da6}")
mfilter.Enabled = False
mfilter.Save
WScript.Echo "done"


Enabling a Filter

The following examples show how to enable a filter.

Visual Basic Example

Use the following Visual Basic code to enable an ISA Web filter:

Set objWebFilter = objFPC.Arrays.GetContainingArray.Extensions.WebFilters.Item(Guid)
objWebFilter.Enabled = True
objWebFilter.Save

Visual Basic Scripting Edition Example

To enable the filter, create a file called Enable.vbs, and then insert the following code:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
Set mfilter = filters("{5b6f6af3-3928-44a3-90f6-c96295c51da6}")
mfilter.Enabled = True
mfilter.Save
WScript.Echo "done"


Deleting a Filter

The following examples show how to delete a filter.

Visual Basic Example

Use the following Visual Basic code to remove an ISA Web filter.

Set objWebFilters = objFPC.Arrays.GetContainingArray.Extensions.WebFilters
objWebFilters.Remove (Guid)
objWebFilters.Save

Visual Basic Scripting Edition Example

To delete the filter, create a file called Delete.vbs, and then insert the following code:

set FPC = WScript.CreateObject("FPC.Root")
Set filters = FPC.Arrays.GetContainingArray.Extensions.WebFilters
filters.Remove("{5b6f6af3-3928-44a3-90f6-c96295c51da6}")
filters.Save
WScript.Echo "done"


Registration

Web filters to be used by the ISA Web proxy service have to be registered under ISA/Arrays/ISAPI-Filters. The administrator will then have access to filter activation through ISA Management.

There are two steps in the filter registration process:

  1. Setup, including copying the filter DLL to an appropriate location, and adding the filter to ISA storage. This process is shown in Web Filter Setup.
  2. Subscription, by using the GetFilterVersion function. This action assigns the notification for which the filter will be called. Subscription occurs each time the ISA Web proxy service is restarted.


Self-Registering Web Filters

You can create a Web (ISAPI) filter that enables self-registration of the filter. The code is demonstrated in the Web filter sample provided with this documentation. The sample extends ISA Management by adding a Web (ISAPI) filter and displaying the filter's information in the tool's results pane. The sample files are in the Web_filters directory, under the samples directory in the SDK.

This section contains the following topics:

  • Building the ISA Web Filter Sample
  • ISA Web Filter Sample Administration Steps


Building the ISA Web Filter Sample

The sample is included in the samples folder of the SDK, in the subfolder Web_filters.

To build the ISA Web filter included in the SDK

  1. Open Microsoft Visual Studio®.
  2. Open the sample workspace, webresponsemodifier.dsw.
  3. To see the project files, on the View menu, click workspace.
  4. Press the F7 key to build the sample.

These steps create webresponsemodifier.dll.


ISA Web Filter Sample Administration Steps

ISA and IIS let you accumulate server request chunks into a complete request. The Webresponsemodifier sample filter is an example that collects the response chunks and then allows you to change them depending on the complete request.

This section contains the following topics:

  • Register the Web Filter From the Command Line
  • Unregister the Web Filter From the Command Line
  • Add the Web Filter to ISA


Register the Web Filter From the Command Line

To install the filter, type this line at the command prompt:

regsvr32 Webresponsemodifier.dll

This command is carried out by the code in the function DllRegisterServer in the Webresponsemodifier sample. The filter developer writes this function. The code from the Webresponsemodifier filter sample is shown as follows.

// DllRegisterServer - Adds entries to the system registry
STDAPI DllRegisterServer(void)
{
    HRESULT hr = RegisterWebFilter(true);
    return FAILED(hr) ? S_FALSE : S_OK;
}


Unregister the Web Filter From the Command Line

To uninstall the filter, type this line at the command prompt:

regsvr32 -u Webresponsemodifier.dll

This command is also carried out by a function that the filter developer writes. The code from the Webresponsemodifier sample is shown here.

// DllUnregisterServer - Removes entries from the system registry

STDAPI DllUnregisterServer(void)
{
    HRESULT hr = RegisterWebFilter(false);
    return hr;
}


Add the Web Filter to ISA

To implement the sample filter and display the filter in the results pane of ISA Management, use the RegisterWebFilter function to register the filter with ISA. This function is also called by the DllRegisterServer and DllUnregisterServer functions.

The following RegisterWebFilter function code is taken from the file WebFltrRegister.cpp, included in the Webresponsemodifier directory:

static HRESULT RegisterWebFilter(bool fRegister)
{
    HRESULT hr;
    ISALIB::IFPC *pIISA  = NULL;

    // Get instance of filter admin object.
    hr = CoInitialize(NULL);

    if (FAILED(hr)) return hr;

    hr = CoCreateInstance(
        CLSID_FPC,
        NULL,
        CLSCTX_SERVER,
        IID_IFPC,
        (void**)&pIISA);

    if (FAILED(hr)) return hr;

    ISALIB::IFPCArrays *pIISAArrs = pIISA->Arrays;
    ISALIB::IFPCArray  *pIISAArr =  pIISAArrs->GetContainingArray();
    ISALIB::IFPCExtensions *pIExtensions =  pIISAArr->Extensions;
    ISALIB::IFPCWebFilters *pWebFilters = pIExtensions->WebFilters;
    ISALIB::IFPCWebFilter *pFilter = NULL;
    if (fRegister)
    {
        _bstr_t bstr(StrGuid);

        try
        {
            pFilter =  pWebFilters->Add(bstr,"ISAPI Filter",FilterRelativePath,ISALIB::fpcFilterPriority_Medium,ISALIB::fpcFilterDirectionBoth);
            pFilter->PutDescription("Filter Description");
            pFilter->PutVendor("Microsoft");
            pFilter->PutVersion("1.0");
        //  pFilter->PutEnabled(TRUE);
        }
        catch(_com_error& err)
        {
            if(err.Error() != HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS))
            {
                hr = E_FAIL;
            }
        }

        if (pFilter)
        {
            pFilter->Save();
        }
    }
    else
    {
        try
        {

            pWebFilters->Remove(StrGuid);
        }
        catch(_com_error& err)
        {
            if(err.Error() != HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))
            {
                hr = E_FAIL;
            }
        }

    }

    pWebFilters->Save();
    pWebFilters->Refresh();

    if(pIISA)
        pIISA->Release();

    CoUninitialize( );

    return hr;
}


Web Filter Samples

Sample Web (ISAPI) filters developed by using the ISA SDK are provided in the Samples\Web_filters directory on the ISA CD-ROM in the SDK directory. The following samples are provided:

  • Webresponsemodifier


Webresponsemodifier

The implemenation of ISAPI in ISA Server allows you to accumulate request chunks, to form a complete request, by means of a Web filter.

The Webresponsemodifier filter collects the response chunks and then allows you to change them depending on the complete response. This filter is an adaptation of the filter that IIS uses for compression. (Original filter was written by David Treadwell in July 1997.)

The filter works with two notifications. In SF_NOTIFY_Send_Raw_Data, it collects the response's chunks, but sends 0 bytes instead of the chunks. Then, when all the chunks of this response have passed SF_NOTIFY_Send_Raw_Data notifications, ISA Server thinks the complete response was sent. It therefore calls the SF_NOTIFY_End_Of_Request notification. The filter sends the complete response in the SF_NOTIFY_End_Of_Request notification.


Pass-Through Authentication

With pass-through authentication, a client can send credentials directly to an upstream server, without sending credentials to the local ISA Server.

In a simple scenario, the downstream ISA Server does not request credentials at all, while the upstream server requires authentication from the client. The process works as follows:

  • The client requests an object from the ISA Server.
  • The ISA Server routes the request to an upstream server, which requests credentials from the client.
  • The client returns the credentials, by way of the ISA Server, directly to the upstream server. The downstream ISA Server does not access the client credentials.

Note that in this case, Web filters running on the ISA Server will not access the credentials passed by the client to the upstream server.

In another scenario, both the ISA Server and the upstream server require credentials. In this case, the process works as follows:

  • The client connects to the ISA Server.
  • The ISA Server requests credentials, as dictated by publishing or access policy rules.
  • The client returns credentials to the ISA Server.
  • The ISA Server passes the request to the upstream server.
  • The upstream server requests client credentials.
  • The client returns credentials to the ISA Server.
  • The ISA Server recognizes the client as already authenticated, and passes the credentials to the upstream server.


ISAPI: Comparing IIS and ISA

The ISA Web proxy service supports the Web (ISAPI) filter extensibility model, allowing third-party developers to examine and change the HTTP request-and-response flow by using Web filters. ISAPI extensions are not supported.

The ISA Web proxy service manages communication with clients, and therefore does not rely on IIS. The ISA Web proxy service provides the functions necessary for the implementation of Web filters. Web filters developed for IIS will work with the ISA Web proxy service because the APIs are unchanged.

There are several important differences between ISAPI support in IIS and in ISA.

Architecture

Web (ISAPI) filters for IIS are typically installed on a Web server. Web filters for ISA are installed on an ISA server, between the Web server and the Web client, and therefore act as conduits for requests to all external and internal sites. There is therefore no local site or content, and no direct access to Web server files.

Functions

The support for general ISAPI functions, server support functions, and notification-specific functions in ISA differs slightly from IIS. The following table compares support for ISAPI functions in IIS and in ISA Server.

Function | Task | ISA Server Support | IIS Support
GetServerVariable |  | Yes. Not all variables are supported | Yes.
AddResponseHeaders |  | Yes. | Yes.
WriteClient |  | Yes. | Yes.
AllocMem |  | Yes. | Yes.
ServerSupportFunction | SF_REQ_ADD_HEADERS_ON_DENIAL | Yes. | Yes.
 | SF_REQ_DISABLE_NOTIFICATIONS | Yes. | Yes.
 | SF_REQ_GET_CONNID | Returns 0 | Supported by versions until IIS 4.0; otherwise, returns 0
 | SF_REQ_GET_PROPERTY only for SF_PROPERTY_INSTANCE_NUM_ID | Returns 0 | Yes.
 | SF_REQ_NORMALIZE_URL | Yes. | Yes.
 | SF_REQ_SEND_RESPONSE_HEADER | Yes. | Yes.
 | SF_REQ_SET_NEXT_READ_SIZE | Yes. | Yes.
 | SF_REQ_SET_PROXY_INFO | No. | Yes.
SF_NOTIFY_SEND_RESPONSE |  | Not used when the Web proxy sends a response. Used when a filter generates a response using the SF_REQ_SEND_RESPONSE_HEADERS server support function. | Yes.
SF_STATUS_REQ_FINISHED_KEEP_CONN |  | Treated the same as SF_STATUS_REQ_FINISHED. After this notification is received, the connection is closed. | Treated the same as SF_STATUS_REQ_FINISHED, except that the server should keep the TCP session open if the option was negotiated.

Administration

Administration, setup, and registration are significantly different in ISA. For specific information and procedures see Web Filter Setup and Registration.

IIS stores configuration information in the Microsoft Active Directory™, whereas the ISA Web proxy service uses the ISA administration COM objects to store and retrieve filter configuration information.

Note Web filters developed for Microsoft Proxy Server 2.0 are not binary-compatible with ISA because of new notifications, setup requirements, and storage functionality.


Managing the ISA Server Cache

The ISA administration COM objects allow you to administer the cache programmatically, automate administrative tasks related to the cache, and extend cache performance by using the FetchURL method.

This section contains the following topics:

  • Introduction to the ISA Server Cache Objects
  • Extending the Cache


Introduction to the ISA Server Cache Objects

The ISA Server cache is administered through the cache COM objects. The objects are described briefly here and in more detail in the ISA Server reference section.

See the ISA Server administration object model to view how the cache-related objects fit into the entire object hierarchy.

FPCCache Object

The FPCCache object is primarily a container for most of the configuration objects listed below. You can access the FPCCacheConfiguration and FPCCacheContents objects directly through this object. You can access the FPCActiveCacheConfiguration, FPCFTPCacheConfiguration, and FPCHTTPCacheConfiguration objects through the FPCCacheConfiguration object.

This object is a property of the FPCArray object and administers the cache for the entire array.

FPCCacheConfiguration Object

The FPCCacheConfiguration object is primarily a container for the FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration objects, which provide access to, respectively, the active caching, HTTP caching, and FTP caching configuration settings.

FPCActiveCacheConfiguration Object

The FPCActiveCacheConfiguration object provides access to the active cache configuration settings of an ISA Server computer.

Active caching is the opposite of passive caching, which is caching in reaction to a specific user request for content. If there is room in the cache, the requested object will be stored in the cache.

Through active caching, ISA can automatically determine the most popular Web sites visited by its clients, determine how frequently those sites update their content, and then automatically obtain and cache the new content when the old content in the cache has expired. Once it is activated, active caching works automatically.

FTPCacheConfiguration Object

The FTPCacheConfiguration object provides access to the FTP cache configuration settings of an ISA Server computer. FTP caching is the caching of FTP objects. You can use this object to choose whether to activate FTP object caching and configure FTP caching settings.

HTTPCacheConfiguration Object

The HTTPCacheConfiguration object provides access to the HTTP cache configuration settings of an ISA Server computer. HTTP caching is the caching of HTTP objects. You can use this object to choose whether to activate HTTP object caching and configure HTTP caching settings.

FPCCacheContents Object

The FPCCacheContents object permits greater control over active caching through the FPCCacheContents.FetchUrl method. This method is used to specify to the cache the URLs to be prefetched or actively retrieved from the Internet and stored in the cache.

FPCScheduledContentDownload Collection

The FPCScheduledContentDownload collection allows you to create a list of predefined scheduled content download tasks. Each task is represented by an FPCScheduledContentDownloadConfig object.

FPCCacheDrive Object and FPCCacheDrives Collection

The FPCCacheDrive object represents a single cache-drive object of an ISA Server computer, and the FPCCacheDrives collection represents a collection of cache drives. The FPCCacheDrive objects allow an administrator to programmatically access and adjust the size of the drives.


Extending the Cache

You can use the FetchUrl method to extend the cache or to delete a cached object using FetchUrl.

This section contains the following topics:

  • Using FetchUrl to Extend the Cache
  • Using FetchUrl to Delete a Cached Object


Using FetchUrl to Extend the Cache

The Web proxy service normally fetches objects from the Internet and caches them automatically as proxy clients request them (passive caching). In addition, the Web proxy service automatically keeps certain popular objects "fresh" within its cache by fetching them itself (active caching). However, occasions occur when an application needs a mechanism to override these automatic operations and exercise greater control over the source of objects that are placed in the cache, or the length of time that they are to remain cached. For example, an application may need to:

  • Make data downloaded from a nonstandard network source (such as a satellite or private network) accessible to Web browsers as if it were normal Internet data.
  • Update certain objects within the Web proxy's cache on a fixed schedule.
  • Place objects in the Web proxy's cache that would normally not be cached.

This function facilitates these operations by allowing an application to cause the Web proxy service to fetch an object from a given location (FetchUrl) and store the object in its cache. The object may also be assigned a new name (CacheUrl), which Web proxy clients will use to retrieve the object from Web proxy cache and/or assigned a particular Time to Live (TTL) within the cache.

FetchURL Usage Examples

Here are three examples of how you might use the FetchURL method.

Example 1

Consider a proxy installation with a very slow Internet connection that requires quick access to the fictional Web site called "fiction.microsoft.com". One solution to this problem would be for the owners of fiction.microsoft.com to produce a CD-ROM that contained all the content found on their Web site and mail it weekly to the proxy customer. An application could use this function to cause the proxy to fetch the data from the CD-ROM and store it in the cache as if it were data from the Internet fiction.microsoft.com site, with a TTL of one week. A complication is that the proxy only supports the HTTP, FTP, and gopher protocols, so the data cannot be fetched directly from the CD-ROM. There are several possible solutions to this problem:

  • The data on the CD-ROM could be copied into the publishing directory of an HTTP or FTP server or a publishing server could be configured to directly serve the data from the CD-ROM. This is a good solution if the data is provided as normal files (HTML, GIF, and so on) without any HTTP headers already added from the original publishing server, fiction.microsoft.com. If the files already contained HTTP headers from fiction.microsoft.com, serving the data from another HTTP server would add a second set of headers which would render the objects unintelligible to the proxy or to browsers.
  • If the files already contain a set of HTTP headers (for example, if they were the product of a raw Internet download of the contents of fiction.microsoft.com instead of a copy of the data files from the fiction.microsoft.com Web servers), the easiest solution might be to write an alternative HTTP server application that would serve up the data files without adding HTTP headers. The HTTP server application would call FetchUrl to listen on the external socket and receive the data before it gets to the Web proxy (w3proxy) service. This would allow the application to have complete control over the data being sent to the Web proxy service. This method is also particularly useful when the application needs to perform simple housekeeping operations on cached objects such as generating a "304 Not Modified" HTTP response to leave an object unmodified but extend its TTL, or a "404 Gone" response to delete an object from the cache.

Example 2

In a Web hosting scenario, your organization may regularly update part of the information on its Web site. All or part of the Web site data can be cached on an ISA Server cache. When the Web site information changes, the cache will have to be updated. You can use the FetchUrl method to streamline the update process. In the central database for the Web site information, create an application that generates a file listing all of the files that have changed. Use FetchUrl to retrieve that file. Parse the file to create a list of files that require updating. Then use FetchUrl to retrieve each updated file from the database. This use of FetchUrl allows you to update only the cache files that have changed.

Example 3

In a Web hosting scenario, users may upload updated Web objects to your publishing server at unpredictable frequencies. These items will not be cached by ISA Server if the existing cached object still has a valid TTL. You can use FetchURL to delete the cached object from the cache, so that the updated object will be cached.

Remarks

To retrieve an HTTP object in response to a call to FetchUrl, the Web proxy service uses the normal HTTP GET method to the URL specified by FetchUrl. If there is already a cached copy of the URL specified by CacheUrl (either loaded into the proxy previously by normal operations or by an earlier call to FetchUrl) the proxy includes an "If-Modified-Since" HTTP header in the request, also known as a conditional GET. The response to a conditional GET may be either a new copy of the data that will be stored in the cache or an HTTP status code 304 "Not Modified" response which will cause the proxy to extend the TTL of the object without changing the contents of the data in the cache.

If FetchUrl is used on an array rather than a stand-alone server, the object is automatically fetched by the single array member that is the designated owner of that object according to the CARP algorithm.

Example Code

The following code sample demonstrates VBScript usage of FetchUrl.

' When using VBScript, the enum values should be declared as constants
' or explicit numeric values must be used instead

Const fpcTtlIfNone = 1
Const fpcFetchSynchronous = 4

customTTL = 10     '

Set root = CreateObject("FPC.Root")
Set myCache = root.Arrays.GetContainingArray.Cache.CacheContents

' we wish to fetch "http://foo.com/bar.htm" and to store it in the cache under the name "http://cache_server/bar.htm"

myCache.FetchURL "http://foo.com/bar.htm", "http://cache_server/bar.htm",  customTTL,  fpcTtlIfNone +  fpcFetchSynchronous


Using FetchUrl to Delete a Cached Object

You can use the FetchUrl method to delete a cached HTTP object. Deleting objects by means of FetchUrl works for any cached object, whether or not it was cached by using FetchUrl.

To delete an HTTP object from the cache, set lpszFetchUrl = <empty string>, lpszCacheUrl = <cachedURL>, TtlInMinutes = 0 and Flags = 0.

Note With flags = 0, the default flag setting, the operation is performed as a non-blocking operation. If flags = FETCH_SYNCHRONOUS, it is a blocking operation.


Internet Security and Acceleration Server Reference

This section contains reference materials related to the Microsoft Internet Security and Acceleration (ISA) Server 2000 Software Development Kit (SDK). It includes information about ISA administration COM objects, programming interfaces for application filter development, and related structures and enumerated types. This section also provides a glossary of terms and a table of objects and their corresponding globally unique identifiers (GUIDs).

The ISA Server reference section contains the following topics:

  • Administration Reference
  • Firewall Reference
  • Web Filter Reference
  • Error Codes
  • Globally Unique Identifiers
  • Glossary


Administration Reference

This section defines Internet Security and Acceleration (ISA) Server 2000 administration objects and includes descriptions of objects, their properties and methods.

This section contains the following topics:

  • Objects
  • Enumerated Types
  • Log Fields
  • Administration Object Error Codes


Objects

The ISA administration COM object sections display Microsoft® Visual Basic® programming language syntax; however, you can write programs using these objects in any language that supports COM. See ISA Server Administration Object Model for a diagram of the administration COM object hierarchy. The diagram shows the beginning of the hierarchy, starting with the root object.

The administration objects expose two types of application programming interfaces (APIs) — one API allows for configuration of stored ISA settings and the other allows for configuration of services that are currently running. For example, the session monitoring objects (FPCWebSession and FPCFirewallSession) permit programmatic monitoring of sessions currently running, while most other administration COM objects allow for programmatic configuration of various internal ISA settings. For more detailed examples of object use, see ISA Administration Scripting.

  • FPC Object
  • FPCAccessControlEntry Object
  • FPCAccessControlList Collection
  • FPCAccount Object
  • FPCAccounts Collection
  • FPCActiveCacheConfiguration Object
  • FPCAdapter Object
  • FPCAdapters Collection
  • FPCAlert Object
  • FPCAlerts Collection
  • FPCAlertAction Object
  • FPCAlertActions Collection
  • FPCAlertInfo Object
  • FPCAlertNotification Object
  • FPCApplicationFilter Object
  • FPCApplicationFilters Collection
  • FPCArray Object
  • FPCArrays Collection
  • FPCArrayPolicyConfig Object
  • FPCArrayPolicyConfigs Collection
  • FPCAutoDial Object
  • FPCBackupRoute Object
  • FPCBandwidthPriority Object
  • FPCBandwidthPriorities Collection
  • FPCBandwidthRule Object
  • FPCBandwidthRules Collection
  • FPCCache Object
  • FPCCacheConfiguration Object
  • FPCCacheContents Object
  • FPCCacheDrive Object
  • FPCCacheDrives Collection
  • FPCClientAddressSet Object
  • FPCClientAddressSets Collection
  • FPCClientAutoScript Object
  • FPCClientBackupRoute Object
  • FPCClientConfig Object
  • FPCClientConfigSettings Collection
  • FPCClientSettingsSection Object
  • FPCContentGroup Object
  • FPCContentGroups Collection
  • FPCCredentials Object
  • FPCDeniedMethod Object
  • FPCDeniedMethods Collection
  • FPCDestination Object
  • FPCDestinationSet Collection
  • FPCDestinationSets Collection
  • FPCDialupEntry Object
  • FPCDialupEntries Collection
  • FPCDialupNetworkConnections Collection
  • FPCDirectAddressDestination Object
  • FPCDirectAddressDestinations Collection
  • FPCDirectIpDestination Object
  • FPCDirectIpDestinations Collection
  • FPCDiskDrive Object
  • FPCDiskDrives Collection
  • FPCEnterprise Object
  • FPCEnterprisePolicy Object
  • FPCEnterprisePolicies Collection
  • FPCEventDefinition Object
  • FPCEventDefinitions Collection
  • FPCExtensions Object
  • FPCFilterProtocol Object
  • FPCFilterProtocols Collection
  • FPCFirewallClientConfig Object
  • FPCFirewallChaining Object
  • FPCFirewallSession Object
  • FPCFirewallSessions Collection
  • FPCFirewallSessionConnection Object
  • FPCFirewallSessionConnections Collection
  • FPCFTPCacheConfiguration Object
  • FPCHTTPCacheConfiguration Object
  • FPCIpPacketFilter Object
  • FPCIpPacketFilters Collection
  • FPCIpRange Object
  • FPCLAT Collection
  • FPCLATEntry Object
  • FPCLDT Collection
  • FPCLDTEntry Object
  • FPCListenEntry Object
  • FPCListenEntries Collection
  • FPCLog Object
  • FPCLogs Collection
  • FPCNetworkConfiguration Object
  • FPCPolicyElements Object
  • FPCPrimaryRoute Object
  • FPCProtocolConnection Object
  • FPCProtocolConnections Collection
  • FPCProtocolDefinition Object
  • FPCProtocolDefinitions Collection
  • FPCProtocolRule Object
  • FPCProtocolRules Collection
  • FPCServerPublishingRule Object
  • FPCServerPublishingRules Collection
  • FPCPublishing Object
  • FPCRef Object
  • FPCRefs Collection
  • FPCRoutingRule Object
  • FPCRoutingRules Collection
  • FPCSchedule Object
  • FPCSchedules Collection
  • FPCScheduledContentDownload Collection
  • FPCScheduledContentDownloadConfig Object
  • FPCSecurityDescriptor Object
  • FPCServer Object
  • FPCServers Collection
  • FPCSignaledAlert Object
  • FPCSignaledAlerts Collection
  • FPCSiteAndContentRule Object
  • FPCSiteAndContentRules Collection
  • FPCSnapinNode Object
  • FPCSSLCertificate Object
  • FPCSSLCertificates Collection
  • FPCTunnelPortRange Object
  • FPCTunnelPortRanges Collection
  • FPCVendorParametersSet Object
  • FPCVendorParametersSets Collection
  • FPCWebBrowserClientConfig Object
  • FPCWebFilter Object
  • FPCWebFilters Collection
  • FPCWebProxy Object
  • FPCWebPublishingRule Object
  • FPCWebPublishingRules Collection
  • FPCWebRequestConfiguration Object
  • FPCWebSession Object
  • FPCWebSessions Collection
  • FPCWebSessionAdditionalInfo Object


FPC Object

The FPC object is the root of the administration object hierarchy, and provides programmatic access to all of the other FPC objects. For a diagram of the entire hierarchy, see ISA Server Administration Object Model.

Creating this root object is the first step in making any programmatic changes to ISA. Using Visual Basic, you can create it with the following code:

  Dim objFPC As New FPCLib.FPC

The CreateObject function is also available to Visual Basic programmers, and alternatively, the following can be used:

  Dim objFPC
  Set objFPC = CreateObject("FPC.Root")

After the FPC object is created, objects below it in the hierarchy can be accessed through the properties of the root object. The Arrays property returns a collection of all ISA arrays within the root node, and it is through this property that you can access and change configuration settings of server arrays.

For multiple examples of use of the FPC root object, see ISA Administration Scripting.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPC interface.

Remarks

When working from an administration-only computer, do not use the FPC object, as it will not provide access to the enterprise. Scripts run from an administration-only computer should use the FPCDS object, which is functionally identical to the FPC object but provides access to the active directory and therefore, to the enterprise.

In Visual Basic, create the root object for remote administration by using the following code:

  Dim objFPC As New FPCLib.FPCDS

Optionally, you can use the CreateObject function:

  Dim objFPC
  Set objFPC = CreateObject("FPCDS.Root")

The following table compares the FPC and FPCDS objects based on the type of installation on which the object is used.

Installation Scenario | FPC Functionality | FPCDS Functionality
Remote administration only | Fails because FPC looks on that computer for an array. | Works for all arrays for which administrator has permissions.
Stand-alone server | Works, but only for the stand-alone server. | Works for all arrays, but not for astand-alone server.
Array | Works for all arrays for which administrator has permissions. | Works for all arrays for which administrator has permissions.

Note In the remote administration only scenario, you can create an FPC object on a remote stand-alone server by using

  Dim objFPC
  Set objFPC = CreateObject("FPC.Root", <ComputerName>)

Where <ComputerName> is the name of the computer on which the object should be created.

Methods

The following table lists the methods of the FPC root object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.

Properties

The following table lists the properties of the FPC root object.

Property | Description
Arrays | Gets a collection of all ISA arrays.
Enterprise | Gets an object that defines enterprise policy settings.
Type | Gets the type of the array.
VendorParametersSets | Gets a reference to an object that stores vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPC.Arrays Property

Gets a collection of all FPC arrays within the FPC root node. Using this arrays property, you can access individual servers within each array.

VBScript Syntax[VBScript]

[ collFPCArrays = ] FPC.Arrays

C++ Syntax[C++]

HRESULT get_Arrays(
  IFPCArrays **pcollFPCArrays
);

Parameters

collFPCArrays
Reference to an FPCArrays collection.

The property is read-only.

Remarks

The following code uses the Arrays property to access the FPCArray.Name property of the first array in the FPC root object:

Dim objFPC As New fpcLib.FPC
Dim arrayName As String
arrayName = objFPC.Arrays(1).Name

Applies To

FPC


FPC.Enterprise Property

Gets an object that defines the enterprise behavior.

VBScript Syntax[VBScript]

[ oFPCEnterprise = ] FPC.Enterprise

C++ Syntax[C++]

HRESULT get_Enterprise(
  IFPCEnterprise **poFPCEnterprise
);

Parameters

oFPCEnterprise
Reference to the FPCEnterprise object.

The property is read-only.

Applies To

FPC


FPC.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPC.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPC


FPC.Type Property

Gets the type of the array. The type can be:

  • A stand-alone (registry-based) server with a single server in ISA Server Standard edition.
  • A stand-alone (registry-based) server with a single server. in ISA Server Enterprise Edition.
  • An array member, installed for ISA Server Enterprise Edition

VBScript Syntax[VBScript]

[ FPCArrayType = ] FPC.Type

C++ Syntax[C++]

HRESULT get_Type(
  FpcArrayType *pFPCArrayType
);

Parameters

FPCArrayType
Value that specifies the type of ISA array. It can have a value of the FpcArrayType enumerated type.

The property is read-only.

Applies To

FPC


FPC.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up with all other FPC objects.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPC.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **collFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPC


FPCAccessControlEntry Object

The FPCAccessControlEntry object allows you to access and manipulate individual access-control entries of the parent object. An FPCAccessControlEntry object stipulates who can access an object and what type of access will be granted. It also specifies whether the access-control settings can be propagated from the object to any of its children.

An object can have a number of access-control entries, one for each client or group of clients. Access control entries are maintained in an FPCAccessControlList collection.

The FPCAccessControlEntry object is a member of an FPCAccessContolList collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAccessControlEntry interface.

Properties

The following table lists the properties of the FPCAccessControlEntry object.

Property | Description
AccessMask | Gets or sets the access mask for this FPCAccessControlEntry object.
AceFlags | Gets or sets the FPCAccessControlEntry flag values.
AceType | Gets or sets the FPCAccessControlEntry object type.
Flags | Gets or sets the FPCAccessControlEntry flag values.
InheritedObjectType | Gets or sets the FPCAccessControlEntry inherited object type.
ObjectType | Gets or sets the FPCAccessControlEntry object type.
Trustee | Gets or sets the FPCAccessControlEntry trustee.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccessControlEntry.AccessMask Property

Gets or sets the access mask for this FPCAccessControlEntry object.

VBScript Syntax[VBScript]

FPCAccessControlEntry.AccessMask [ = lAccessMask ]

C++ Syntax[C++]

HRESULT get_AccessMask(
  long *plAccessMask
);

HRESULT put_AccessMask(
  long lAccessMask
);

Parameters

lAccessMask

Long value that specifies the access mask for this FPCAccessControlEntry object. Can be a combination of bit values from the FpcIndArrayObjAccessRights enumerated type for a stand-alone server or from the FpcDomainArrayObjAccessRights for an array. These rights are mapped to registry access rights and Active Directory access rights, respectively. Use bit values from the FpcAlertsAccessRights enumerated type for the signaled alerts access mask, and from the FpcSessionsAccessRights enumerated type for the sessions access mask.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.AceFlags Property

Gets or sets the FPCAccessControlEntry flag values.

VBScript Syntax[VBScript]

FPCAccessControlEntry.AceFlags [ = lAceFlag ]

C++ Syntax[C++]

HRESULT get_AceFlags(
  long *plAceFlag
);

HRESULT put_AceFlags(
  long lAceFlag
);

Parameters

lAceFlag
Long value that specifies the FPCAccessControlEntry flag values. It can have a value from the FpcAceFlag enumerated type. These values describe ACE inheritance and audit message generation options. For more information about ACE inheritance, see MSDN.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.AceType Property

Gets or sets the FPCAccessControlEntry object type.

VBScript Syntax[VBScript]

FPCAccessControlEntry.AceType [ = lAceType ]

C++ Syntax[C++]

HRESULT get_AceType(
  long *plAceType
);

HRESULT put_AceType(
  long lAceType
);

Parameters

lAceType
Long value that specifies the FPCAccessControlEntry object type. Can be a combination of bit values from the FpcAceType enumerated type. These values describe types of access control entries (ACE). For more information on ACE, see MSDN.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.Flags Property

Gets or sets the FPCAccessControlEntry flag values.

VBScript Syntax[VBScript]

FPCAccessControlEntry.Flags [ = lFlags ]

C++ Syntax[C++]

HRESULT get_Flags(
  long *plFlags
);

HRESULT put_Flags(
  long lFlags
);

Parameters

lFlags
Long value that specifies the FPCAccessControlEntry flag values. Can be a value from the FpcAceFlagType enumerated type. The FpcAceFlagType enumerated type contains values that indicate the presence of the ObjectType or InheritedObjectType fields in the access-control entry (ACE). For more information on the ObjectType or InheritedObjectType fields, see MSDN.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.InheritedObjectType Property

Gets or sets the FPCAccessControlEntry inherited object type. An inherited object type identifies the type of child object that can inherit an ACE. For more information about ACE inheritance, see MSDN.

VBScript Syntax[VBScript]

FPCAccessControlEntry.InheritedObjectType[ = sInheritedObjectType ]

C++ Syntax[C++]

HRESULT get_InheritedObjectType(
  BSTR *psInheritedObjectType
);

HRESULT put_InheritedObjectType(
  BSTR sInheritedObjectType
);

Parameters

sInheritedObjectType
String value that specifies the FPCAccessControlEntry inherited object type.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.ObjectType Property

Gets or sets the FPCAccessControlEntry object type. The object type identifies a property set, property, extended right, or type of child object, depending on the access rights specified in the AccessMask property. For more information about object types, see MSDN.

VBScript Syntax[VBScript]

FPCAccessControlEntry.ObjectType [ = sObjectType ]

C++ Syntax[C++]

HRESULT get_ObjectType(
  BSTR *psObjectType
);

HRESULT put_ObjectType(
  BSTR sObjectType
);

Parameters

sObjectType
String that specifies the FPCAccessControlEntry object type.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlEntry.Trustee Property

Gets or sets the FPCAccessControlEntry trustee. The trustee is the user account, group account, or logon session to which an ACE applies. For more information about trustees, see MSDN.

VBScript Syntax[VBScript]

FPCAccessControlEntry.Trustee [ = sTrustee ]

C++ Syntax[C++]

HRESULT get_Trustee(
  BSTR *psTrustee
);

HRESULT put_Trustee(
  BSTR sTrustee
);

Parameters

sTrustee
String value that specifies the FPCAccessControlEntry trustee.

This value can take the following forms:

  • Domain account (the logon name used in some versions of Windows NT®) of the form domain\accountname. Domain is the name of the Windows NT domain that contains the user, and accountname is the sAMAccountName property of the specified user, for example: Microsoft\jeffsmit.
  • Well-known security principal that represents special identities defined by the Windows NT security system, such as everyone, local system, principal self, authenticated user, creator owner, and so on. The objects representing the well-known security principals are stored in the WellKnown Security Principals container under the Configuration container.
  • Built-in group that represents the built-in user groups defined by the Windows NT security system. It has the form BUILTIN\groupname where groupname is the name of the built-in user group, for example, BUILTIN\Administrators. The objects representing the built-in groups are stored in the Builtin container beneath the domain container.
  • SID (string format) of the specified user, which is the objectSID property of the specified user, for example: S-1-5-32-548. You can convert this to string form using the ConvertSidToStringSid function in the Win32 Security API.

The property is read-write.

Applies To

FPCAccessControlEntry


FPCAccessControlList Collection

The FPCAccessControlList collection contains a group of FPCAccessControlEntry objects that provide finely tuned access control to the same ADSI object for different clients. In general, different providers implement different access controls. The object's behavior is thus highly provider-specific.

Before you can work with FPCAccessControlEntry objects, you must obtain the FPCAccessControlList to which they belong. FPCAccessControlList collections are managed by security descriptors and can be in the form of a discretionary access-control list or a system access-control list. Using this collection, you can retrieve FPCAccessControlEntry objects, add new objects to the list, or remove existing objects.

The FPCAccessControlList object is a property of an FPCSecurityDescriptor object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAccessControlList interface.

Methods

The following table lists the methods of the FPCAccessControlList collection.

Method | Description
AddAce | Adds an FPCAccessControlEntry object to the list.
CopyAccessList | Returns a copy of the current FPCAccessControlList collection.
RemoveAce | Removes an FPCAccessControlEntry object from the list.

Properties

The following table lists the properties of the FPCAccessControlList collection.

Property | Description
AceCount | Gets the number of FPCAccessControlEntry objects in the collection.
AclRevision | Gets or sets the FPCAccessControlList collection revision number.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccessControlList.AceCount Property

Gets the number of FPCAccessControlEntry objects in the collection.

Syntax

[ lCount = ] FPCAccessControlList.AceCount

C++ Syntax[C++]

HRESULT get_AceCount(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCAccessControlEntry objects in the collection.

The property is read-only.

Applies To

FPCAccessControlList


FPCAccessControlList.AclRevision Property

Gets or sets the FPCAccessControlList collection revision number.

VBScript Syntax[VBScript]

FPCAccessControlList.AclRevision [ = lAclRevision ]

C++ Syntax[C++]

HRESULT get_AclRevision(
  long *plAclRevision
);

HRESULT put_AclRevision(
  long lAclRevision
);

Parameters

lAclRevision
Long value that specifies the FPCAccessControlList collection revision number, using a value from the FpcSDRevision enumerated type.

The property is read-write.

Applies To

FPCAccessControlList


FPCAccessControlList.AddAce Method

Adds an FPCAccessControlEntry object to the list.

VBScript Syntax[VBScript]

AccessControlList.AddAce( oFPCAccessControlEntry )

C++ Syntax[C++]

HRESULT AddAce(
  IFPCAccessControlEntry *poFPCAccessControlEntry
);

Parameters

oFPCAccessControlEntry
Reference to the FPCAccessControlEntry object being added.

Applies To

FPCAccessControlList


FPCAccessControlList.CopyAccessList Method

Returns a copy of the current FPCAccessControlList collection.

VBScript Syntax[VBScript]

[ collFPCAccessControlList = ] FPCAccessControlList.CopyAccessList()

C++ Syntax[C++]

HRESULT CopyAccessList(
  IFPCAccessControlList **ppcollFPCAccessControlList
);

Return Values

collFPCAccessControlList
Reference to an FPCAccessControlList collection.

Applies To

FPCAccessControlList


FPCAccessControlList.RemoveAce Method

Removes an FPCAccessControlEntry object from the list.

VBScript Syntax[VBScript]

FPCAccessControlList.RemoveAce( oFPCAccessControlEntry )

C++ Syntax[C++]

HRESULT RemoveAce(
  IFPCAccessControlEntry *poFPCAccessControlEntry
);

Parameters

oFPCAccessControlEntry
Reference to the FPCAccessControlEntry object to be removed.

Applies To

FPCAccessControlList


FPCAccount Object

The FPCAccount object defines an account for a user or a group of users. You can use this object to determine the account type, modify the account status, read the domain and name of the account, and allow or deny access.

The FPCAccount object is a member of the FPCAccounts collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAccount interface.

Properties

The following table lists the properties of the FPCAccount object.

Property | Description
Account | Gets or sets the domain and name of the account.
AccountStatus | Gets or sets a value that determines whether this account serves as an "Include" entity or an "Exclude" entity in the collection.
AccountType | Gets the type of the account.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCAccount object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccount.Account Property

Gets or sets the domain and name of the account.

VBScript Syntax[VBScript]

FPCAccount.Account [ = sAccount ]

C++ Syntax[C++]

HRESULT get_Account(
  BSTR *psAccount
);

HRESULT put_Account(
  BSTR sAccount
);

Parameters

sAccount
String that specifies the domain and name, in domain\accountname format.

The property is read-write.

Applies To

FPCAccount


FPCAccount.AccountStatus Property

Gets or sets a value that determines whether this account is included in or excluded from the list of accounts to which a rule applies.

VBScript Syntax[VBScript]

FPCAccount.AccountStatus [ = Status ]

C++ Syntax[C++]

HRESULT get_AccountStatus(
  FpcIncludeStatus *pStatus
);

HRESULT put_AccountStatus(
  FpcIncludeStatus Status
);

Parameters

Status
Specifies the status. It can have a value from the FpcIncludeStatus enumerated type.

The property is read-write.

Applies To

FPCAccount


FPCAccount.AccountType Property

Gets the account type.

VBScript Syntax[VBScript]

[ Type = ] FPCAccount.AccountType

C++ Syntax[C++]

HRESULT get_AccountType(
  FpcAccountTypes *pType
);

Parameters

Type
Integer value that specifies the account type. It can have a value from the FpcAccountTypes enumerated type. These values indicate whether the account type is a user, a group of users, a domain of users, an alias or a predefined account.

The property is read-only.

Applies To

FPCAccount


FPCAccount.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCAccount object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCAccount.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to an FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAccount


FPCAccounts Collection

The FPCAccounts collection holds a group of FPCAccount objects. You can use this collection to define a set of accounts to be associated with a site and content rule or a protocol rule. This set is defined by accounts to include and by accounts to exclude. For example, you can define a set of "all users but John" by adding the account name for the all-users group as "included" and then adding John's account as "excluded".

This collection is a property of the FPCSiteAndContentRule and FPCProtocolRule objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCAccounts interface.

Methods

The following table lists the methods of the FPCAccounts collection.

Method | Description
Add | Creates a new account object, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCAccount object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an account from the collection.
RemoveAll | Clears the collection of all objects.

Properties

The following table lists the properties of the FPCAccounts collection.

Property | Description
Count | Gets the number of account objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAccounts.Add Method

Creates a new account object, inserts it into the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCAccount = ] FPCAccounts.Add( sAccount, iAccountStat )

C++ Syntax[C++]

HRESULT Add(
  BSTR sAccount,
  FpcIncludeStatus iAccountStat,
  IFPCAccount **ppoFPCAccount
);

Parameters

sAccount
Required. String that specifies the account. Specified in domain\accountname format.
iAccountStat
Required. Integer flag. Can have a value from the FpcIncludeStatus enumerated type.

Return Values

oFPCAccount
Returns a reference to the FPCAccount object.

Applies To

FPCAccounts


FPCAccounts.Count Property

Gets the number of account objects in the collection.

VBScript Syntax[VBScript]

[ lCount= ] FPCAccounts.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCAccount objects.

The property is read-only.

Applies To

FPCAccounts


FPCAccounts.Item Method

Gets the given FPCAccount object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCAccounts.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCAccount **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve. Specified in domain\accountname format.

Return Values

vItem
If successful, gets a reference to an object of type FPCAccount; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Remarks

The vIndex parameter is in the form of an index or a name. For example, the following code specifies an account by name in domain\accountname format.

FPCAccounts.Item("africa\john")

Applies To

FPCAccounts


FPCAccounts.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCAccounts.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCAccounts


FPCAccounts.Remove Method

Removes an account from the collection.

VBScript Syntax[VBScript]

FPCAccounts.Remove( iIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT viIndex
);

Parameters

iIndex
Required. Name or one-based index of the FPCAccount object to remove.

Remarks

The vIndex parameter is either in the form of an index or a name. For example, the following code specifies an account by name and is in domain\accountname format.

FPCAccounts.Remove("africa\john")

Applies To

FPCAccounts


FPCAccounts.RemoveAll Method

Removes all objects from the collection.

VBScript Syntax[VBScript]

FPCAccounts.RemoveAll( )

C++ Syntax[C++]

HRESULT RemoveAll();

Applies To

FPCAccounts


FPCActiveCacheConfiguration Object

The FPCActiveCacheConfiguration object provides access to the active cache configuration settings of an ISA Server computer. Active caching is a mechanism for automatically obtaining and caching updated content for popular sites. The objects FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration provide access to all ISA cache configuration settings. These three objects are accessed through properties of the FPCCacheConfiguration object, which serves as a container for the three.

The FPCActiveCacheConfiguration object is a property of an FPCCacheConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCActiveCacheConfiguration interface.

Remarks

When active caching is enabled, if you are using a dial-up connection to the Internet, then the computer will automatically dial out to the Internet service provider (ISP) to retrieve this content.

Methods

The following table lists the methods of the FPCActiveCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any unsaved changes to the configuration.
ResetToDefaults | Discards any changes made to the active cache configuration, saved or unsaved, and reverts to the default cache configuration.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCActiveCacheConfiguration object.

Property | Description
ActiveCachingEnable | Gets or sets whether active caching is enabled.
ActiveCachingPolicy | Gets or sets the policy for pre-fetching of popular objects into the cache.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCActiveCacheConfiguration.ActiveCachingEnable Property

Gets or sets whether active caching is enabled.

VBScript Syntax[VBScript]

FPCActiveCacheConfiguration.ActiveCachingEnable [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_ActiveCachingEnable(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_ActiveCachingEnable(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether active caching is enabled.

The property is read-write.

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.ActiveCachingPolicy Property

Gets or sets the policy for how actively popular objects are prefetched into the cache.

VBScript Syntax[VBScript]

FPCActiveCacheConfiguration.ActiveCachingPolicy [ = iPolicy ]

C++ Syntax[C++]

HRESULT get_ActiveCachingPolicy(
  FpcActiveCachingPolicy *piPolicy
);

HRESULT put_ActiveCachingPolicy(
  FpcActiveCachingPolicy iPolicy
);

Parameters

iPolicy
A value from the FPCActiveCachingPolicy enumerated type.

The property is read-write.

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCActiveCacheConfiguration.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.ResetToDefaults Method

Discards any changes made to the active cache configuration and reverts to the default cache configuration.

VBScript Syntax[VBScript]

FPCActiveCacheConfiguration.ResetToDefaults()

C++ Syntax[C++]

HRESULT ResetToDefaults();

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.Save Method

Saves the active cache configuration to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCActiveCacheConfiguration.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCActiveCacheConfiguration


FPCActiveCacheConfiguration.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCCacheConfiguration object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCActiveCacheConfiguration.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCActiveCacheConfiguration


FPCAdapter Object

The FPCAdapter object represents a single network adapter of an ISA server. You can connect to the Internet through either a direct or dial-up connection. If you choose a direct connection, you need to set up an external network adapter. This object represents that adapter and is a member of the the FPCAdapters collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAdapter interface.

Properties

The following table lists the properties of the FPCAdapter object.

Property | Description
Description | Gets the name of the adapter.
IpAddresses | Gets a comma-delimited list of all IP addresses bound to the adapter.
Selected | Gets or sets a Boolean value indicating whether this network adapter is selected to be included in the Local Address Table (LAT) construction.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAdapter.Description Property

Gets the name of the network adapter.

VBScript Syntax[VBScript]

[ sDescription = ] FPCAdapter.Description

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

Parameters

sDescription
String that specifies the description of the adapter.

The property is read-only.

Applies To

FPCAdapter


FPCAdapter.IpAddresses Property

Gets a comma-delimited list of all IP addresses bound to the network adapter.

VBScript Syntax[VBScript]

[ sIpAddresses = ] FPCAdapter.IpAddresses

C++ Syntax[C++]

HRESULT get_IpAddresses(
  BSTR *psIpAddresses
);

Parameters

sIpAddresses
String that specifies the IP addresses.

The property is read-only.

Applies To

FPCAdapter


FPCAdapter.Selected Property

Gets or sets a Boolean value that indicates whether the network adapter is selected to be included in the Local Address Table (LAT) construction.

VBScript Syntax[VBScript]

FPCAdapter.Selected [ = bSelected ]

C++ Syntax[C++]

HRESULT get_Selected(
  VARIANT_BOOL *pbSelected
);

HRESULT put_Selected(
  VARIANT_BOOL bSelected
);

Parameters

bSelected
Boolean value that specifies whether the network adapter is selected to be included in the Local Address Table (LAT) construction.

The property is read-write.

Remarks

This property is used in conjunction with the FPCLAT.AddFromSelectedAdapters method to generate the LAT. The state of bSelected is not retained when the object is discarded. This means that if you use this object to set bSelected to TRUE, and then discard this object, the state of bSelected is not stored in memory.

Applies To

FPCAdapter


FPCAdapters Collection

The FPCAdapters collection provides access to a group of FPCAdapter objects. You can connect to the Internet through either a direct or dial-up connection. If you choose a direct connection, you need to set up an external network adapter. This collection represents a group of adapters and is a property of the FPCServer object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCAdapters interface.

Methods

The following table lists the methods of the FPCAdapters collection.

Method | Description
Item | Retrieves the given FPCAdapter object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.

Properties

The following table lists the properties of the FPCAdapters collection.

Property | Description
Count | Gets the number of FPCAdapter objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAdapters.Count Property

Gets the number of FPCAdapter objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCAdapters.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCAdapter objects.

The property is read-only.

Applies To

FPCAdapters


FPCAdapters.Item Method

Gets the given FPCAdapter object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCAdapters.Item( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  IFPCAdapter **pvItem
);

Parameters

lIndex
Required. IP or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCAdapter; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCAdapters


FPCAdapters.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCAdapters.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCAdapters


FPCAlert Object

The FPCAlert object defines an alert. When a specific event occurs, this object determines the actions to be taken in response to that event. The FPCAlert object also defines the three thresholds that determine when actions will be taken. Alerts allow for an administrator to be notified when certain events take place, and to decide which actions should be taken in advance. Properties of the actions to be taken are accessed through the FPCAlertActions collection.

For a more detailed example of using the FPCAlert object, see Adding a Custom Event and Alert.

This object is a member of the FPCAlerts collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAlert interface.

Methods

The following table lists the methods of the FPCAlert object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetDefinitions | Sets the following definitions of the alert: event GUID, server name, and the additional key. The three must be set simultaneously because they should form a unique triplet.

Properties

The following table lists the properties of the FPCAlert object.

Property | Description
Actions | Gets a reference to the FPCAlertActions collection.
AdditionalKey | Gets the index to the additional key table of the event associated with this alert.
Description | Gets or sets the description of the alert object.
Enabled | Gets or sets whether the alert is enabled.
EventGUID | Gets the GUID of the event type on which the alert is based.
EventsBeforeRaise | Gets or sets a minimal number of events that trigger the alert before the alert's actions can be executed.
MinEventsPerSecond | Gets or sets a minimal frequency of events that trigger the alert before the alert's actions can be executed.
MinutesBeforeReRaise | Gets or sets a time interval to wait before alert's actions can be executed again.
Name | Gets or sets the name of the alert object.
Password | Sets the password for the credentials of the command-line action.
ServerName | Gets the name of the server allowed to signal this alert.
UserName | Gets or sets the user name for the credentials of the command-line action.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCAlert object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlert.Actions Property

Gets a reference to the FPCAlertActions collection, which is a collection of FPCAlertAction objects. Each FPCAlertAction object defines an FPC action.

VBScript Syntax[VBScript]

[ collFPCAlertActions = ] FPCAlert.Actions

C++ Syntax[C++]

HRESULT get_Actions(
  IFPCAlertActions **pcollFPCAlertActions
);

Parameters

collFPCAlertActions
Reference to the FPCAlertActions collection.

The property is read-only.

Applies To

FPCAlert


FPCAlert.AdditionalKey Property

Gets the index to the additional-key table of the event associated with this alert.

Additional keys serve as a means to subdivide event objects into related subevents; for example, to subdivide a disk-full event into log-disk-full or system-disk-full subevents. This allows for either different alerts that are specific to subevents or one alert that is specific to all subevents.

For example, an administrator can add separate alerts for each separate subevent by specifying an EventGUID and AdditionalKey property for each subevent. The AdditionalKey property is the index used in the additional-key table. Alternatively, an administrator can treat all subevents as a singular event by specifying EventGUID and setting AdditionalKey to zero. In other words, the index zero is reserved and shouldn't be overloaded with a user-specific additional key.

If an event has no subevents, then the value of this property should be -1.

The additional-key table cannot be modified; an administrator can only select keys from the table.

VBScript Syntax[VBScript]

[ lKey = ] FPCAlert.AdditionalKey

C++ Syntax[C++]

HRESULT get_AdditionalKey(
  long *plKey
);

Parameters

lKey
Long value that specifies the index.

The property is read-only.

Applies To

FPCAlert


FPCAlert.Description Property

Gets or sets the description of the alert object.

VBScript Syntax[VBScript]

FPCAlert.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String value that describes the alert object.

The property is read-write.

Applies To

FPCAlert


FPCAlert.Enabled Property

Gets or sets whether the alert is enabled.

VBScript Syntax[VBScript]

FPCAlert.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the alert is enabled.

The property is read-write.

Applies To

FPCAlert


FPCAlert.EventGUID Property

Gets the globally unique identifier (GUID) of the event type on which the alert is based. Each event invariably has a unique GUID.

VBScript Syntax[VBScript]

[ sGuid = ] FPCAlert.EventGUID

C++ Syntax[C++]

HRESULT get_EventGUID(
  BSTR *psGuid
);

Parameters

sGuid
String that specifies the GUID.

The property is read-only.

Applies To

FPCAlert


FPCAlert.EventsBeforeRaise Property

Gets or sets a minimal number of events that trigger the alert before the alert's actions can be executed.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second, and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The EventsBeforeRaise property sets the threshold for the number of times the alert can be triggered before it will execute its actions.

VBScript Syntax[VBScript]

FPCAlert.EventsBeforeRaise [ = lThreshold ]

C++ Syntax[C++]

HRESULT get_EventsBeforeRaise(
  long *plThreshold
);

HRESULT put_EventsBeforeRaise(
  long lThreshold
);

Parameters

lThreshold
Long value that specifies the threshold.

The property is read-write.

Applies To

FPCAlert


FPCAlert.MinEventsPerSecond Property

Gets or sets a minimal frequency of events that trigger the alert before the alert's actions can be executed.The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second, and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinEventsPerSecond property sets the threshold for the number of events per second the alert should be triggered to execute its actions.

VBScript Syntax[VBScript]

FPCAlert.MinEventsPerSecond [ = lThreshold ]

C++ Syntax[C++]

HRESULT get_MinEventsPerSecond(
  long *plThreshold
);

HRESULT put_MinEventsPerSecond(
  long lThreshold
);

Parameters

lThreshold
Long value that specifies the threshold of the signaling rate.

The property is read-write.

Applies To

FPCAlert


FPCAlert.MinutesBeforeReRaise Property

Gets or sets a time interval to wait before alert's actions can be executed again.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second, and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinutesBeforeReRaise property sets the minimal number of minutes to wait before an alert can execute its actions again.

VBScript Syntax[VBScript]

FPCAlert.MinutesBeforeReRaise [ = lInterval ]

C++ Syntax[C++]

HRESULT get_MinutesBeforeReRaise(
  long *plInterval
);

HRESULT put_MinutesBeforeReRaise(
  long lInterval
);

Parameters

lInterval
Long value that specifies the time interval.

Remarks

The property can have the following values:

Value | Description
Positive integer | The number of minutes to wait.
0 | The alert can execute its actions again immediately.
-1 | The alert must be reset before it can again execute its actions. You can do this through ISA Management or by using the FPCAlertNotification.ResetNotificationState method.

The property is read-write.

Applies To

FPCAlert


FPCAlert.Name Property

Gets or sets the name of the alert object.

VBScript Syntax[VBScript]

FPCAlert.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the alert object.

The property is read-write.

Applies To

FPCAlert


FPCAlert.Password Property

Sets the password for the credentials of the command-line action.

The UserName and Password properties are used to restrict the privileges of commands invoked by the alert service. For example, an account could be created with appropriate privileges, and the name and password of that account could then be used by the FPCAlert object. The UserName and Password properties are used only for run-program actions.

VBScript Syntax[VBScript]

FPCAlert.Password [ = sPassword ]

C++ Syntax[C++]

HRESULT put_Password(
  BSTR sPassword
);

Parameters

sPassword
String that specifies the password.

The property is write-only.

Applies To

FPCAlert


FPCAlert.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCAlert.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCAlert


FPCAlert.Save Method

Saves the object's configuration to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCAlert.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCAlert


FPCAlert.ServerName Property

Gets the name of the server that is allowed to signal this alert.

VBScript Syntax[VBScript]

[ sName = ] FPCAlert.ServerName

C++ Syntax[C++]

HRESULT get_ServerName(
  BSTR *psName
);

Parameters

sName
String that specifies the server name.

The property is read-only.

Remarks

When the sName parameter is an empty string, or (""), all servers are allowed to signal this alert.

Applies To

FPCAlert


FPCAlert.SetDefinitions Method

Sets the following definitions of the alert: event globally unique identifier (GUID), server name, and the additional key. The three must be set simultaneously because they form a unique triplet.

VBScript Syntax[VBScript]

FPCAlert.SetDefinitions( sEventGUID, sServerName, lAdditionalKey )

C++ Syntax[C++]

HRESULT SetDefinitions(
  BSTR sEventGUID,
  BSTR sServerName,
  long lAdditionalKey
);

Parameters

sEventGUID
String that specifies the GUID of the event that triggers this alert.
sServerName
Optional. String that specifies the name of the server that is allowed to signal this alert.
lAdditionalKey
Optional. Long value of the additional key. The key is an index to a table defined in the corresponding event.

Applies To

FPCAlert


FPCAlert.UserName Property

Gets or sets the user name for the credentials of the command-line action.

The UserName and Password properties are used to restrict the privileges of commands invoked by the alert service. For example, an account could be created with appropriate privileges, and the name and password of that account could then be used by the FPCAlert object. The UserName and Password properties are used only for run-program actions.

VBScript Syntax[VBScript]

FPCAlert.UserName [ = sName ]

C++ Syntax[C++]

HRESULT get_UserName(
  BSTR *psName
);

HRESULT put_UserName(
  BSTR sName
);

Parameters

sName
String that specifies the user name.

The property is read-write.

Applies To

FPCAlert


FPCAlert.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCAlert object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCAlert.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlert


FPCAlerts Collection

FPCAlerts is a collection of individual FPCAlert objects. Each object within this collection defines an alert. When a specific event occurs, this object determines the actions to be taken in response to that event. The FPCAlert object also defines the three thresholds that determine when actions will be taken. Alerts allow for an administrator to be notified when certain events take place and to decide which actions should be taken in advance.

The FPCAlerts collection is a property of the FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCAlerts interface.

Methods

The following table lists the methods of the FPCAlerts collection.

Method | Description
Add | Creates a new alert, inserts it into the collection, and returns a reference to it.
Item | Returns the given FPCAlert object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an alert from the collection.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCAlerts collection.

Property | Description
Count | Gets the number of FPCAlert objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCAlerts collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlerts.Add Method

Creates a new alert, inserts it into the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCAlert = ] FPCAlerts.Add( sName, sEventGUID, sServerName, lAdditionalKey )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  BSTR sEventGUID,
  BSTR sServerName,
  long lAdditionalKey,
  IFPCAlert **ppoFPCAlert
);

Parameters

sName
Required. String that specifies the name of the alert. Can be used in FPCAlerts to retrieve the alert.
sEventGUID
Required. String that specifies the GUID of the event that triggers this alert.
sServerName
Optional. String that specifies the name of the server that is allowed to signal alerts. If no server is specified, any server is allowed to signal the alert.
lAdditionalKey
Optional. Long value that specifies the index to the additional-key table of this alert's event. This parameter's value should be less than or equal to the number of additional event keys. If the corresponding event has no additional-key table, then this parameter should be set to -1.

Return Values

oFPCAlert
Returns a reference to the FPCAlert object.

Applies To

FPCAlerts


FPCAlerts.Count Property

Gets the number of alert objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCAlerts.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCAlert objects.

The property is read-only.

Applies To

FPCAlerts


FPCAlerts.Item Method

Gets the given FPCAlert object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCAlerts.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCAlert **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, gets a reference to an object of type FPCAlert; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCAlerts


FPCAlerts.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCAlerts.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCAlerts


FPCAlerts.Remove Method

Removes an alert from the collection.

VBScript Syntax[VBScript]

FPCAlerts.Remove( iIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT iIndex
);

Parameters

iIndex
Required. Name or one-based index of the FPCAlert object to remove.

Applies To

FPCAlerts


FPCAlerts.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCAlerts.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCAlerts


FPCAlerts.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCAlerts collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCAlerts.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlerts


FPCAlertAction Object

The FPCAlertAction object defines a single action. Each action is carried out when an ISA alert signals that an action needs to be taken. You can determine the kind of action you want taken by using the Type property. The Type property determines whether the action will be to send mail, to issue a command, to write to a log, or another task.

This object is a member of the FPCAlertActions collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAlertAction interface.

Methods

The following table lists the methods of the FPCAlertAction object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCAlertAction object.

Property | Description
Enabled | Gets or sets whether the action is enabled.
Name | Gets the name of the alert action.
Parameters | Gets an array of strings that specify optional parameters for the action.
Type | Gets the type identifier (ID) of the alert action.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCAlertAction object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlertAction.Enabled Property

Gets or sets whether the action is enabled.

VBScript Syntax[VBScript]

FPCAlertAction.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the action is enabled.

The property is read-write.

Applies To

FPCAlertAction


FPCAlertAction.Name Property

Gets or sets the name of the alert action.

VBScript Syntax[VBScript]

FPCAlertAction.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the alert action.

The property is read-write.

Applies To

FPCAlertAction


FPCAlertAction.Parameters Property

Gets an array of strings that specify optional parameters for an action. The parameters are set by using the methods of the FPCAlertActions collection.

VBScript Syntax[VBScript]

[ sParameters  = ] FPCAlertAction.Parameters

C++ Syntax[C++]

HRESULT get_Parameters(
  VARIANT *psParameters
);

Parameters

sParameters
Array of strings that specifies optional parameters.

The property is read-only.

Remarks

The following table shows the values of sParameters.

Action | param1 | param2 | param3 | param4
log event | none | none | none | none
command | command line | none | none | none
stop/start service | service name | service name | service name | service name
send mail | SERVER= x (1) | TO= x (2) | CC= x (3) | FROM= x (4)
(1) - x is an address or IP of an SMTP mail server (2) - x is a list of To recipients, space delimited (3) - x is a list of Cc recipients, space delimited (4) - x is a valid e-mail address of the sender

Applies To

FPCAlertAction


FPCAlertAction.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCAlertAction.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCAlertAction


FPCAlertAction.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCAlertAction.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCAlertAction


FPCAlertAction.Type Property

Gets the type identifier (ID) of the alert action. You can use this property to determine specifically what this action does.

VBScript Syntax[VBScript]

[ ActionType = ] FPCAlertAction.Type

C++ Syntax[C++]

HRESULT get_Type(
  FpcActionTypes *pActionType
);

Parameters

ActionType
Action type identifier (ID). It can have a value from the FpcActionTypes enumerated type.

The property is read-only.

Applies To

FPCAlertAction


FPCAlertAction.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCAlertAction object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCAlertAction.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlertAction


FPCAlertActions Collection

The FPCAlertActions collection accesses a group of FPCAlertAction objects. Each object in this collection defines an action. An action is carried out when an ISA alert signals that an action needs to be taken.

FPCAlertActions is a property of the FPCAlert object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCAlertActions interface.

Methods

The following table lists the methods of the FPCAlertActions collection.

Method | Description
Item | Retrieves the given FPCAlertAction object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the collection's configuration to persistent storage.
SetCommand | Creates a new command-line action in the collection, or updates the command-line action if it already exists.
SetLogEvent | Creates a new log-event action in the collection, or updates the log-event action if it already exists.
SetSendMail | Creates a new send-mail action in the collection, or updates the send-mail action if it already exists.
SetStartServices | Creates a new start-services action in the collection, or updates the start-services action if it already exists.
SetStopServices | Creates a new stop-services action in the collection, or updates the stop-services action if it already exists.
Unset | Sets the action specified to a disabled state.

Properties

The following table lists the properties of the FPCAlertActions collection.

Property | Description
Count | Gets the number of FPCAlertAction objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCAlertActions collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAlertActions.Count Property

Gets the number of alert action objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCAlertActions.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCAlertAction objects.

The property is read-only.

Applies To

FPCAlertActions


FPCAlertActions.Item Method

Gets the given FPCAlertAction object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCAlertActions.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCAlertAction **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, gets a reference to an object of type FPCAlertAction; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCAlertActions


FPCAlertActions.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCAlertActions.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCAlertActions


FPCAlertActions.Save Method

Saves the configuration of all FPCAlertAction objects in the collection to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCAlertActions.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCAlertActions


FPCAlertActions.SetCommand Method

Creates a new command-line action in the collection, or updates the command-line action if it already exists.

VBScript Syntax[VBScript]

[ oFPCAlertAction = ] FPCAlertActions.SetCommand( sActionName, sCommand )

C++ Syntax[C++]

HRESULT SetCommand(
  BSTR sActionName,
  BSTR sCommand,
  IFPCAlertAction **ppoFPCAlertAction
);

Parameters

sActionName
Required. String that specifies the name of the action. Can be used in the FPCAlertActions collection to retrieve the action.
sCommand
Required. String that specifies the command-line action.

Return Values

oFPCAlertAction
Gets a reference to an FPCAlertAction object for the new or updated command-line action.

Applies To

FPCAlertActions


FPCAlertActions.SetLogEvent Method

Creates a new log-event action in the collection, or updates the log-event action if it already exists.

VBScript Syntax[VBScript]

[ oFPCAlertAction = ] FPCAlertActions.SetLogEvent( sActionName )

C++ Syntax[C++]

HRESULT SetLogEvent(
  BSTR sActionName,
  IFPCAlertAction **ppoFPCAlertAction
);

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.

Return Values

oFPCAlertAction
Returns a reference to the FPCAlertAction object for the new or updated log-event action.

Applies To

FPCAlertActions


FPCAlertActions.SetSendMail Method

Creates a new send-mail action in the collection, or updates the send-mail action if it already exists.

VBScript Syntax[VBScript]

[ oFPCAlertAction = ] FPCAlertActions.SetSendMail( sActionName, sServer, sToField, sCcField, sFromField )

C++ Syntax[C++]

HRESULT SetSendMail(
  BSTR sActionName,
  BSTR sServer,
  BSTR sToField,
  BSTR sCcField,
  BSTR sFromField,
  IFPCAlertAction **ppoFPCAlertAction
);

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.
sServer
Required. String that specifies a name or IP address of an SMTP server.
sToField
Required. String that specifies a space-delimited list of mail recipients that appear on the To list.
sCcField
Required. String that specifies a space-delimited list of mail recipients that appear on the CC list.
sFromField
Required. String that specifies a valid e-mail address of the sender.

Return Values

oFPCAlertAction
Gets a reference to the FPCAlertAction object for the new or updated send-mail action.

Applies To

FPCAlertActions


FPCAlertActions.SetStartServices Method

Creates a new start-services action in the collection, or updates the start-services action if it already exists.

VBScript Syntax[VBScript]

[ oFPCAlertAction = ] FPCAlertActions.SetStartServices( sActionName, iServices )

C++ Syntax[C++]

HRESULT SetStartServices(
  BSTR sActionName,
  FpcServices iServices,
  IFPCAlertAction **ppoFPCAlertAction
);

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.
iServices
Required. Integer value that specifies which services to start. It can have a value from the FpcServices enumerated type.

Return Values

oFPCAlertAction
Returns a reference to an FPCAlertAction object for the new or updated start-services action.

Applies To

FPCAlertActions


FPCAlertActions.SetStopServices Method

Creates a new stop-services action in the collection, or updates the stop-services action if it already exists.

VBScript Syntax[VBScript]

[ oFPCAlertAction = ] FPCAlertActions.SetStopServices( sActionName, iServices )

C++ Syntax[C++]

HRESULT SetStopServices(
  BSTR sActionName,
  FpcServices iServices,
  IFPCAlertAction **ppoFPCAlertAction
);

Parameters

sActionName
Required. String that specifies the name of the action. Can be used to retrieve the action.
iServices
Required. Integer that specifies which FPC services to stop. It can have a value from the FpcServices enumerated type.

Return Values

oFPCAlertAction
Returns a reference to an FPCAlertAction object for the new or updated stop-services action.

Applies To

FPCAlertActions


FPCAlertActions.Unset Method

Sets the action specified to a disabled state.

VBScript Syntax[VBScript]

FPCAlertActions.Unset( ActionType )

C++ Syntax[C++]

HRESULT Unset(
  FpcActionTypes ActionType
);

Parameters

ActionType
Required. Specifies the action type to be unset. It can have a value from the FpcActionTypes enumerated type.

Applies To

FPCAlertActions


FPCAlertActions.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCAlertActions collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCAlertActions.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCAlertActions


FPCAlertInfo Object

The FPCAlertInfo object represents information about a signaled alert. The information stored in this object can be retrieved all at once by using the GetAllProperties method. To reset ISA to signal an alert associated with this object, use the EventGUID, ServerName, and AdditionalKey properties. Use the values of these three properties in a call to the FPCAlertNotification.ResetNotificationState method.

The FPCAlertInfo object is created with a statement like the following:

Dim FPCAlertInfo as new ALERTSRVLib.AlertInfo

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAlertInfo interface.

Methods

The following table lists the methods of the FPCAlertInfo object.

Method | Description
GetAllProperties | Returns all properties of the FPCAlertInfo object at once.

Properties

The following table lists the properties of the FPCAlertInfo object.

Property | Description
AdditionalKey | Gets the additional key of the alert.
Description | Gets the description of the alert.
EventGUID | Gets the globally unique identifier (GUID) of the event that signaled the alert.
FirstSignalTime | Gets a DATE data type of the time of the first alert signaling (in GMT).
Name | Gets the name of the alert.
ServerName | Gets either the name of the current server, or an empty string representing an alert from all ISA servers.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Alertsrv.idl.


FPCAlertInfo.AdditionalKey Property

Gets the additional key of the alert. The additional key will be one of the following: (-1), which represents no additional keys; (0), which represents any additional keys; or the actual value of an individual additional key.

VBScript Syntax[VBScript]

[ lAdditionalKey = ] FPCAlertInfo.AdditionalKey

C++ Syntax[C++]

HRESULT get_AdditionalKey(
  long *plAdditionalKey
);

Return Values

lAdditionalKey
Long value that specifies the additional key of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.Description Property

Gets the description of the alert.

VBScript Syntax[VBScript]

[ sDescription = ] FPCAlertInfo.Description

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

Return Values

sDescription
String that specifies the description of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.EventGUID Property

Gets the globally unique identifier (GUID) of the event that signaled the alert.

VBScript Syntax[VBScript]

[ sEventGUID = ] FPCAlertInfo.EventGUID

C++ Syntax[C++]

HRESULT get_EventGUID(
  BSTR *psEventGUID
);

Return Values

sEventGUID
String that specifies the GUID of the event that signaled the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.FirstSignalTime Property

Gets a DATE value of the time of the first signaling of the alert in system time (AKA, UTC, or GMT).

VBScript Syntax[VBScript]

[ dFirstSignalTime = ] FPCAlertInfo.FirstSignalTime

C++ Syntax[C++]

HRESULT get_FirstSignalTime(
  DATE *pdFirstSignalTime
);

Return Values

dFirstSignalTime
DATE value of the first signaling of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.GetAllProperties Method

Gets all the properties of the FPCAlertInfo object at once.

VBScript Syntax[VBScript]

FPCAlertInfo.GetAllProperties( sEventGuid, sServerName,
lAdditionalKey, sName, sDescription, dFirstSignalTime)

C++ Syntax[C++]

HRESULT GetAllProperties(
  BSTR *psEventGuid,
  BSTR *psServerName,
  long *plAdditionalKey,
  BSTR *psName,
  BSTR *psDescription,
  DATE *pdFirstSignalTime
);

Parameters

sEventGuid
[out] String that specifies the globally unique identifier (GUID) of the event that signaled the alert.
sServerName
[out] String that specifies the server name.
lAdditionalKey
[out] Long value that specifies the additional key.
sName
[out] String that specifies the name of the alert.
sDescription
[out] String that specifies the description of the alert.
dFirstSignalTime
[out] DATE value that specifies the system time of the first signaling of the alert.

Applies To

FPCAlertInfo


FPCAlertInfo.Name Property

Gets the name of the alert.

VBScript Syntax[VBScript]

[ sName = ] FPCAlertInfo.Name

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

Return Values

sName
String that specifies the name of the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertInfo.ServerName Property

Gets the name of the ISA server for which the alert is defined, or an empty string representing an alert that applies to all servers within an array.

VBScript Syntax[VBScript]

[ sServerName = ] FPCAlertInfo.ServerName

C++ Syntax[C++]

HRESULT get_ServerName(
  BSTR *psServerName
);

Return Values

sServerName
String that specifies the name of the server that issued the alert.

This property is read only.

Applies To

FPCAlertInfo


FPCAlertNotification Object

The FPCAlertNotification object is the COM interface to ISA's alert service, and is used to signal an event or reset an alert's state. The alert service is responsible for recording information about events reported by ISA services, and for executing actions triggered by each event.

It is possible to enumerate all signaled alerts for a server using this object.

The FPCAlertNotification object is created with a statement such as the following:

Dim FPCAlertNotification as new ALERTSRVLib.AlertNotification

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCAlertNotification interface.

Methods

The following table lists the methods of the FPCAlertNotification object.

Method | Description
EnumSignaledAlerts | Returns a variant containing an array of variants. Each entry in the variant array contains an interface to an FPCAlertInfo object.
ResetNotificationState | Resets the notification state of the designated alert.
SignalEvent | Signals an event.
Signal_N_Events | Signals an event n times.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Alertsrv.idl.


FPCAlertNotification.EnumSignaledAlerts Method

Gets a variant containing an array of variants. Each entry in the variant array contains an interface to an FPCAlertInfo object.

VBScript Syntax[VBScript]

[ VarAlert = ] FPCAlertNotification.EnumSignaledAlerts

C++ Syntax[C++]

HRESULT EnumSignaledAlerts(
  VARIANT *pVarAlert
);

Parameters

VarAlert
An array of variants containing interfaces to FPCAlertInfo objects.

Applies To

FPCAlertNotification


FPCAlertNotification.ResetNotificationState Method

Resets the notification state of the designated alert. This method should be used to reset the threshold information of an alert collected by the alert service until the present time. ResetNotificationState is required for alerts that execute their action only once before the administrator manually resets them. For more information about alerts, see the ISA Server product documentation.

VBScript Syntax[VBScript]

FPCAlertNotification.ResetNotificationState( sAlertName )

C++ Syntax[C++]

HRESULT ResetNotificationState(
  BSTR sAlertName
);

Parameters

sAlertName
Required. String that specifies the name of the alert to be reset.

Applies To

FPCAlertNotification


FPCAlertNotification.SignalEvent Method

ISA services use this method to signal an event, as a part of the alert service. If an alert exists for the event and the event is in a state where it can trigger an alert, actions will be taken to notify the administrator of the event. Third-party filters can also use this method to signal an event.

VBScript Syntax[VBScript]

FPCAlertNotification.SignalEvent( sGuid, sServerName, lAdditionalKey,
  sShortDesc, sLongDesc, lEventID, sEventSource, varEventStrings,
  varEventData, shEventCategory, shEventType)

C++ Syntax[C++]

HRESULT SignalEvent(
  BSTR sGuid,
  BSTR sServerName,
  long lAdditionalKey,
  BSTR sShortDesc,
  BSTR sLongDesc,
  long lEventID,
  BSTR sEventSource,
  VARIANT varEventStrings,
  VARIANT varEventData,
  short shEventCategory,
  short shEventType
);

Parameters

sGuid
Required. String that specifies the globally unique identifier (GUID) of the event triggering this alert.
sServerName
Required. String that specifies the name of the server triggering this alert. This should contain the value NULL or an empty string, specifying the local server.
lAdditionalKey
Required. Long value that contains the index to additional keys' table for this event. This parameter cannot be zero. If the signaled event has no additional-key table, the parameter should be -1.
sShortDesc
String that contains a brief description of the run-time event. Used as the subject line for a send-mail action.
sLongDesc
String that contains a detailed description of the run-time event. Used as the body text for a send-mail action.
lEventID
Long value that contains the identifier (ID) of the event to be reported to the system event log.
sEventSource
String that contains source name for the event reported.
varEventStrings
Variant that contains insertion strings for the event reported.
varEventData
Variant that contains raw data for the event reported.
shEventCategory
Short that contains category of the event reported.
shEventType
Short that contains type of the event reported.

Remarks

The parameter sEventSource is similar to the lpSourceName parameter of the Win32® RegisterEventSource function. Other parameters for this function are similar to parameters in the Win32 function ReportEvent, as shown in the following table. For more information, see the relevant function in MSDN.

SignalEvent Parameter | ReportEvent Parameter
lEventID | dwEventID
varEventStrings | lpStrings
varEventData | lpRawData
shEventCategory | wCategory
shEventType | wType

Applies To

FPCAlertNotification


FPCAlertNotification.Signal_N_Events Method

Used by ISA services to signal n instances of an event, as part of the alert service. If an alert exists for the event and the event is in a state where it can trigger an alert, actions will be taken to notify the event. Third-party application filters can also use this method to signal instances of an event.

VBScript Syntax[VBScript]

FPCAlertNotification.Signal_N_Events( sGuid, sServerName, lAdditionalKey, lEventsCount,
  sShortDesc, bstrLongDesc, lEventID, sEventSource, varEventStrings,
  varEventData, shEventCategory, shEventType)

C++ Syntax[C++]

HRESULT Signal_N_Events(
  BSTR sGuid,
  BSTR sServerName,
  long lAdditionalKey,
  long lEventsCount,
  BSTR sShortDesc,
  BSTR sLongDesc,
  long lEventID,
  BSTR sEventSource,
  VARIANT varEventStrings,
  VARIANT varEventData,
  short shEventCategory,
  short shEventType
);

Parameters

sGuid
Required. String that specifies the globally unique identifier (GUID) of the event triggering this alert.
sServerName
Required. String that specifies the name of the server triggering this alert. This should contain the value NULL or an empty string, specifying the local server.
lAdditionalKey
Required. Index to additional keys' table for this event. This parameter cannot be zero. If the signaled event has no additional-key table, the parameter should be -1.
lEventsCount
Required. Counts the number of instances of the event.
sShortDesc
Required. String that contains a brief description of the run-time event. Used as the subject line for a send-mail action.
sLongDesc
Required. String that contains a detailed description of the run-time event. Used as the body text for a send-mail action.
lEventID
Required. Long value that contains the identifier (ID) of the event to be reported to the system event log.
sEventSource
Required. String that contains source name for the event reported.
varEventStrings
Required. Variant that contains insertion strings for the event reported.
varEventData
Required. Variant that contains raw data for the event reported.
shEventCategory
Required. Short value that contains category of the event reported.
shEventType
Required. Short value that contains type of the event reported.

Remarks

The parameter sEventSource is similar to the lpSourceName parameter of the Win32 RegisterEventSource function. Other parameters for this function are similar to parameters in the Win32 function ReportEvent, as shown in the following table. For more information, see the relevant function in MSDN.

Signal_N_Events Parameter | ReportEvent Parameter
lEventID | dwEventID
varEventStrings | lpStrings
varEventData | lpRawData
shEventCategory | wCategory
shEventType | wType

Note When you use the Signal_N_Events method, you must keep track of the time in which the n instances take place because the alert service assumes that the n instances all occurred at the last second. This differs from the SignalEvent, in which the alert service tracks the time.

Applies To

FPCAlertNotification


FPCApplicationFilter Object

The FPCApplicationFilter object represents a single application filter. Application filters work with the Firewall service to intercept and process data. Application filters can access the data stream or datagrams associated with a session within the Firewall service. The filters are registered with the Firewall service and act in response to events detected by the service. An application filter can perform protocol-specific or system-specific tasks, such as authentication and checking for viruses.

The FPCApplicationFilter object is a member of the FPCApplicationFilters collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCApplicationFilter interface.

Methods

The following table lists the methods of the FPCApplicationFilter object.

Method | Description
CancelWaitForChanges | For use in C and C++ programming only; cancels the registration established by the WaitForChanges method.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
WaitForChanges | For use in C and C++ programming only; registers to wait for an event indicating that an FPCVendorParametersSet context has changed.

Properties

The following table lists the properties of the FPCApplicationFilter object.

Property | Description
Description | Gets or sets the vendor-supplied description of the application filter.
Enabled | Gets or sets whether the application filter is enabled.
Guid | Gets the globally unique identifier (GUID) that identifies the application filter. The vendor of the filter provides the GUID.
Name | Gets or sets the vendor-supplied name of the application filter.
Protocols | Gets a collection of the application filter protocols.
Vendor | Gets or sets the name of the vendor of the application filter.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCApplicationFilter object's storage.
Version | Gets or sets the vendor-supplied version of the application filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCApplicationFilter.CancelWaitForChanges Method

Cancels the registration established by the WaitForChanges method.

Note This method can only be used in C and C++ programming languages. It cannot be used with DCOM.

C++ Syntax[C++]

HRESULT CancelWaitForChanges();


FPCApplicationFilter.Description Property

Gets or sets the vendor-supplied description of the application filter.

Note Though C++ syntax is provided for this property, C++ programmers should set this property using the parameters of the IFWXFilterAdmin::InstallFilter method.

VBScript Syntax[VBScript]

FPCApplicationFilter.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the vendor-supplied description.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Enabled Property

Gets or sets whether the application filter is enabled.

VBScript Syntax[VBScript]

FPCApplicationFilter.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the application filter is enabled.

The property is read-write.

Note When you've changed a setting by using the Enabled property, and save the change by using the Save method, the Firewall service must be restarted for your change to take effect. To stop and restart the Firewall service, use the FPCArray.SendRestartNotification method.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Guid Property

Gets the globally unique identifier (GUID) that identifies the application filter. The vendor of the filter provides the GUID.

VBScript Syntax[VBScript]

[ sGuid = ] FPCApplicationFilter.Guid

C++ Syntax[C++]

HRESULT get_Guid(
  BSTR *psGuid
);

Parameters

sGuid
String that specifies the GUID for the application filter.

The property is read-only.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Name Property

Gets or sets the vendor-supplied name of the application filter.

Note Though C++ syntax is provided for this property, C++ programmers should set this property using the parameters of the IFWXFilterAdmin::InstallFilter method.

VBScript Syntax[VBScript]

FPCApplicationFilter.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the vendor-supplied name.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Protocols Property

Gets a collection of application filter protocols.

VBScript Syntax[VBScript]

[ collFPCFilterProtocols = ] FPCApplicationFilter.Protocols

C++ Syntax[C++]

HRESULT get_Protocols(
  IFPCFilterProtocols **pcollFPCFilterProtocols
);

Parameters

collFPCFilterProtocols
Reference to the FPCFilterProtocols collection.

The property is read-only.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCApplicationFilter.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCApplicationFilter


FPCApplicationFilter.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCApplicationFilter.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCApplicationFilter


FPCApplicationFilter.Vendor Property

Gets or sets the name of the vendor of the application filter.

Note Though C++ syntax is provided for this property, C++ programmers should set this property using the parameters of the IFWXFilterAdmin::InstallFilter method.

VBScript Syntax[VBScript]

FPCApplicationFilter.Vendor [ = sVendor ]

C++ Syntax[C++]

HRESULT get_Vendor(
  BSTR *psVendor
);

HRESULT put_Vendor(
  BSTR sVendor
);

Parameters

sVendor
String that specifies the vendor's name.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilter.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCApplicationFilter object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCApplicationFilter.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCApplicationFilter


FPCApplicationFilter.Version Property

Gets or sets the vendor-supplied version of the application filter.

Note Though C++ syntax is provided for this property, C++ programmers should set this property using the parameters of the IFWXFilterAdmin::InstallFilter method.

VBScript Syntax[VBScript]

FPCApplicationFilter.Version [ = sVersion ]

C++ Syntax[C++]

HRESULT get_Version(
  BSTR *psVersion
);

HRESULT put_Version(
  BSTR sVersion
);

Parameters

sVersion
String that specifies the vendor-supplied version.

The property is read-write.

Applies To

FPCApplicationFilter


FPCApplicationFilter.WaitForChanges Method

Registers to wait for an event indicating that the contents of the application filter storage have changed. This includes changes to the VendorParametersSet property associated with the filter, or other information in the filter storage, such as registered protocols.

Note This method can only be used in C and C++ programming languages. It cannot be used with DCOM.

C++ Syntax[C++]

HRESULT WaitForChanges(
  DWORD hEvent
);

Parameters

hEvent
An event to be signaled whenever the storage content of the FPCApplicationFilter object has changed.

Remarks

This method allows application filters to handle dynamic configuration changes smoothly.


FPCApplicationFilters Collection

This collection provides access to all application filters, stored as FPCApplicationFilter objects. Each FPCApplicationFilter object represents a single application filter.

This object is a property of an FPCExtensions object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCApplicationFilters interface.

Methods

The following table lists the methods of the FPCApplicationFilters collection.

Method | Description
Item | Retrieves the given FPCApplicationFilter object from the collection.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCApplicationFilters collection.

Property | Description
Count | Gets the number of application filter objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCApplicationFilters collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCApplicationFilters.Count Property

Gets the number of application filter objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCApplicationFilters.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of application filter objects.

The property is read-only.

Applies To

FPCApplicationFilters

See Also

FPCApplicationFilter


FPCApplicationFilters.Item Method

Gets the given FPCApplicationFilter object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCApplicationFilters.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCApplicationFilters **pvItem
);

Parameters

vIndex
Required. One-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCApplicationFilter; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCApplicationFilters


FPCApplicationFilters.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCApplicationFilters.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCApplicationFilters


FPCApplicationFilters.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCApplicationFilters.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCApplicationFilters


FPCApplicationFilters.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCApplicationFilters collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCApplicationFilters.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCApplicationFilters


FPCArray Object

The FPCArray object defines a single ISA array. An ISA array is a group of one or more ISA servers that are treated and administered as a single, logical entity. Each array has multiple configurable properties.

For examples using the FPCArray object, see ISA Administration Scripting .

This object is a member of the FPCArrays collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCArray interface.

Methods

The following table lists the methods of the FPCArray object.

Method | Description
Backup | Backs up the array configuration to a file.
GetSecurityDescriptor | Gets the security descriptor for the array.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Restore | The Restore method reads the array's information from a file.
Save | Saves the object's configuration to persistent storage.
SendRestartNotification | Gets a list of services that must be restarted and sets a flag under each server for each service that should be restarted.
SetSecurityDescriptor | Sets the security descriptor for the array.

Properties

The following table lists the properties of the FPCArray object.

Property | Description
Alerts | Gets a collection of all alerts in the array.
ArrayPolicy | Gets an object holding all array policyconfiguration for this array.
BackupArrayDescription | Gets the description of the array that was backed up
BackupArrayMode | Gets the mode of the array that was backed up.
BackupArrayName | Gets the name of the array that was backed up.
BackupArrayType | Gets the type of the array that was backed up.
BackupComment | Gets the comment from a backup file.
BackupCreatedTime | Gets the time the backup was created.
BackupServerDescription | Gets the description of the server that was backed up.
BackupServerName | Gets the name of the server that was backed up.
BandwidthRules | Gets a collection of all bandwidth rules in this array.
Cache | Gets an object holding all cache configuration for this array.
ClientConfig | Gets an object containing client configuration information.
Components | Gets a set of flags indicating the components that are installed in this array.
CreatedTime | Gets a DATE data type that specifies the creation time of the object.
Description | Gets or sets the description of the array in the form of a string.
DomainName | Gets the array's domain name.
Extensions | Gets an FPCExtensions object.
LastModifiedTime | Gets a DATE data type that specifies the last modification time of the object.
Logging | Gets an object holding all log configuration for this array.
Name | Gets or sets the name of the array.
NetworkConfiguration | Gets an object holding all network configuration for this array.
PolicyElements | Gets an object holding all policy configuration for this array.
Publishing | Gets a reference to this array's publishing configuration object.
Servers | Gets a collection of all ISA servers in this array.
SiteName | Gets the FPCArray object's site name.
Type | Gets the array's type.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCArray object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArray.Alerts Property

Gets a collection of all alerts in the array. Use this property to read, write, add, delete, or modify the Alerts property for a particular array.

VBScript Syntax[VBScript]

[ collFPCAlerts = ] FPCArray.Alerts

C++ Syntax[C++]

HRESULT get_Alerts(
  IFPCAlerts **pcollFPCAlerts
);

Parameters

collFPCAlerts
Reference to an FPCAlerts collection.

The property is read-only.

Example

The following code uses the Alerts property to return the name of an individual alert:

Dim objFPC As New FPCLib.FPC
Dim alertName As String
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays(1)
alertName = objFPCArray.Alerts(1).Name

Applies To

FPCArray

See Also

FPCAlert


FPCArray.ArrayPolicy Property

Gets an object that holds the array policy information for this array.

VBScript Syntax[VBScript]

[ oFPCArrayPolicy = ] FPCArray.ArrayPolicy

C++ Syntax[C++]

HRESULT get_ArrayPolicy(
  IFPCArrayPolicy **oFPCArrayPolicy
);

Parameters

oFPCArrayPolicy
Reference to an FPCArrayPolicy object.

The property is read-only.

Applies To

FPCArrayPolicy


FPCArray.Backup Method

Backs up the array configuration to a file.

VBScript Syntax[VBScript]

FPCArray.Backup( sFileName, sComment, bOverwrite )

C++ Syntax[C++]

HRESULT Backup (
  BSTR sFileName,
  BSTR sComment,
  VARIANT_BOOL bOverwrite
);

Parameters

sFileName
A string that specifies the name of the file to contain a copy of the array information after the operation is complete.
sComment
Optional. A string that specifies a comment to add to the backup file.
bOverwrite
Optional. A Boolean value that specifies whether to allow an operation to continue when a backup file with the same name already exists.

Remarks

If you perform backup from a remote computer, the path you provide should be local to the server; for example, c:\Backups\MyBackup.bif. The server computer will resolve the path. Do not provide a path that is relative to the remote administration computer.

Applies To

FPCArray


FPCArray.BackupArrayDescription Property

Gets the array's description from a backup file.

VBScript Syntax[VBScript]

[ sArrayDescription = ] FPCArray.BackupArrayDescription ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupArrayDescriptioni (
  BSTR sFileName,
  BSTR *psArrayDescription
);

Parameters

sFileName
A string that specifies the name of the file to contain a backup of the array information.

Return Values

sArrayDescription
Reference to a string that specifies the array description.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupArrayMode Property

Gets the array's mode from a backup file.

VBScript Syntax[VBScript]

[ lComponents = ] FPCArray.BackupArrayMode ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupArrayMode (
  BSTR sFileName,
  BSTR *plComponents
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

lComponents
Long value that specifies the component flags, using values from the FpcComponents enumerated type.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupArrayName Property

Gets the array's name from a backup file.

VBScript Syntax[VBScript]

[ sArrayName = ] FPCArray.BackupArrayName ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupArrayName (
  BSTR sFileName,
  BSTR *psArrayName
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

sArrayName
Reference to a string that specifies the array name.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupArrayType Property

Gets the array's type from a backup file.

VBScript Syntax[VBScript]

[ ArrayType = ] FPCArray.BackupArrayType ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupArrayType (
  BSTR sFileName,
  FpcArrayType *pArrayType
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information.

ReturnValues

ArrayType
The array type. Can have a value from the FpcArrayType enumerated type.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupComment Property

Gets the backup comment from a file.

VBScript Syntax[VBScript]

[ sComment = ] FPCArray.BackupComment ( sFileName )

C++ Syntax[C++]

HRESULT BackupComment (
  BSTR sFileName,
  BSTR *psComment
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

sComment
Reference to a string that contains the backup comment.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupCreatedTime Property

Gets the time that the backup file was created.

VBScript Syntax[VBScript]

[ dTime = ] FPCArray.BackupComment ( sFileName )

C++ Syntax[C++]

HRESULT BackupComment (
  BSTR sFileName,
  DATE *pdTime
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

dTime
DATE value specifying the time that the backup file was created.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupServerDescription Property

Gets the server's description from a backup file.

VBScript Syntax[VBScript]

[ sServerDescription = ] FPCArray.BackupServerDescription ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupServerDescription (
  BSTR sFileName,
  BSTR *psServerDescription
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

sServerDescription
Reference to a string that specifies the server description.

The property is read-only.

Applies To

FPCArray


FPCArray.BackupServerName Property

Gets the server's name from a backup file.

VBScript Syntax[VBScript]

[ sServerName = ] FPCArray.BackupServerName ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupServerName (
  BSTR sFileName,
  BSTR *psServerName
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information.

Return Values

sServerName
Reference to a string that specifies the server name.

The property is read-only.

Applies To

FPCArray


FPCArray.BandwidthRules Property

Gets a collection of all bandwidth rules in the array.

VBScript Syntax[VBScript]

[ collFPCBandwidthRules = ] FPCArray.BandwidthRules

C++ Syntax[C++]

HRESULT get_BandwidthRules(
  IFPCBandwidthRules **pcollFPCBandwidthRules
);

Parameters

collFPCBandwidthRules
Reference to an FPCBandwidthRules collection.

The property is read-only.

Applies To

FPCArray


FPCArray.Cache Property

Gets an object that holds all cache configuration data for this array. Through this object, you can use such properties of the FPCCache object as CacheConfiguration and CacheContents to adjust cache settings.

VBScript Syntax[VBScript]

[ oFPCCache = ] FPCArray.Cache

C++ Syntax[C++]

HRESULT get_Cache(
  IFPCCache **poFPCCache
);

Parameters

oFPCCache
Reference to an FPCCache object.

This property is read-only.

Applies To

FPCArray


FPCArray.ClientConfig Property

Gets a reference to the FPCClientConfig object. The FPCClientConfig object represents the configuration that the firewall client setup application sets for the firewall client and for the client-machine web browsers. It also contains information that firewall clients download periodically from the ISA array, and information that is used for creating the browser configuration script.

VBScript Syntax[VBScript]

[ oFPCClientConfig = ] FPCArray.ClientConfig

C++ Syntax[C++]

HRESULT get_ClientConfig(
  IFPCClientConfig **poFPCClientConfig
);

Parameters

oFPCClientConfig
Reference to an FPCClientConfig object.

This property is read-only.

Applies To

FPCArray


FPCArray.Components Property

Gets a set of flags that indicate the components that are installed in this array.

VBScript Syntax[VBScript]

[ lComponents = ] FPCArray.Components

C++ Syntax[C++]

HRESULT get_Components(
  long *plComponents
);

Parameters

lComponents
Long value that specifies the component flags by using values from the FpcComponents enumerated type.

The property is read-only.

Applies To

FPCArray


FPCArray.CreatedTime Property

Gets a DATE data type that specifies the creation time of the array.

VBScript Syntax[VBScript]

[ dCreatedTime = ] FPCArray.CreatedTime

C++ Syntax[C++]

HRESULT get_CreatedTime(
  DATE *pdCreatedTime
);

Parameters

dCreatedTime
Reference to the DATE data type.

The property is read-only.

Applies To

FPCArray


FPCArray.Description Property

Gets or sets the description of the array. The description is stored as a string.

VBScript Syntax[VBScript]

FPCArray.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the array.

The property is read-write.

Applies To

FPCArray


FPCArray.DomainName Property

Gets the FPCArray object's domain name.

VBScript Syntax[VBScript]

[ sDomainName = ] FPCArray.DomainName

C++ Syntax[C++]

HRESULT get_DomainName(
  BSTR *psDomainName
);

Return Values

sDomainName
Reference to a string that specifies the FPCArray object's domain name.

The property is read-only.

Applies To

FPCArray


FPCArray.Extensions Property

Gets an FPCExtensions object.

VBScript Syntax[VBScript]

[ oFPCExtensions = ] FPCArray.Extensions

C++ Syntax[C++]

HRESULT get_Extensions(
  IFPCExtensions **oFPCExtensions
);

Parameters

oFPCExtensions
Reference to an FPCExtensions object.

The property is read-only.

Applies to

FPCEnterprise


FPCArray.GetSecurityDescriptor Method

Gets the security descriptor for the array. For more information, see the FPCSecurityDescriptor object.

VBScript Syntax[VBScript]

[vSecurityDescriptor = ] FPCArray.GetSecurityDescriptor( lSecurityInfo, bBinary, scope )

C++ Syntax[C++]

HRESULT GetSecurityDescriptor (
  LONG lSecurityInfo,
  VARIANT_BOOL bBinary,
  FpcSecurityScope scope,
  VARIANT *pvSecurityDescriptor
);

Parameters

lSecurityInfo
Long value that specifies security information. For more information, see GetSecurityInfo in MSDN.
bBinary
Boolean value that determines whether you get the security descriptor in binary form.
scope
Specifies the level at which the security descriptor applies by using values from the FPCSecurityScope enumerated type.

Return Values

vSecurityDescriptor
Reference to an FPCSecurityDescriptor object. If you specify that the security descriptor is in binary form, this is a reference to a Win32 security descriptor in self-relative format. For more information on Win32 security descriptors, see MSDN.

Remarks

This method makes use of related Windows functionality. For more information, see GetSecurityInfo in MSDN.

Applies to

FPCEnterprise


FPCArray.LastModifiedTime Property

Gets a DATE data type that specifies the last modification time of the object.

VBScript Syntax[VBScript]

[ dLastModifiedTime = ] FPCArray.LastModifiedTime

C++ Syntax[C++]

HRESULT get_LastModifiedTime(
  DATE *pdLastModifiedTime
);

Parameters

dLastModifiedTime
Reference to the DATE data type.

The property is read-only.

Applies To

FPCArray


FPCArray.Logging Property

Gets an object that holds all log configurations for this array.

VBScript Syntax[VBScript]

[ collFPCLogs = ] FPCArray.Logging

C++ Syntax[C++]

HRESULT get_Logging(
  IFPCLogs **pcollFPCLogs
);

Parameters

collFPCLogs
Reference to an FPCLogs collection.

This property is read-only.

Applies To

FPCArray


FPCArray.Name Property

Gets or sets the name of the array. The name of the array is stored as a string.

VBScript Syntax[VBScript]

FPCArray.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the array name.

The property is read-write.

Applies To

FPCArray


FPCArray.NetworkConfiguration Property

Gets an object that holds all network configuration settings for this array. You can access and manipulate network configurations through this property.

VBScript Syntax[VBScript]

[ oFPCNetworkConfiguration = ] FPCArray.NetworkConfiguration

C++ Syntax[C++]

HRESULT get_NetworkConfiguration(
  IFPCNetworkConfiguration **poFPCNetworkConfiguration
);

Parameters

oFPCNetworkConfiguration
Reference to an FPCNetworkConfiguration object.

This property is read-only.

Applies To

FPCArray


FPCArray.PolicyElements Property

Gets an object that holds all policy configuration for this array. The FPCPolicyElements object itself has many properties that allow you to access important ISA settings — for example, configuration details, all scheduling information, destination sets, client address sets, protocol definitions, all filtering information, and all bandwidth class information. All these settings can be programmatically accessed through the PolicyElements property.

VBScript Syntax[VBScript]

[ oFPCPolicyElements = ] FPCArray.PolicyElements

C++ Syntax[C++]

HRESULT get_PolicyElements(
  IFPCPolicyElements **poFPCPolicyElements
);

Parameters

oFPCPolicyElements
Reference to an FPCPolicyElements object.

This property is read-only.

Example

The following Visual Basic code example uses the PolicyElements property to list the number of schedules within an array:

Dim objFPC As New FPCLib.FPC
Dim objFPCArray As FPCArray
Dim NumSchedules As Integer
Set objFPCArray = objFPC.Arrays(1)
NumSchedules = objFPCArray.PolicyElements.Schedules.Count

Applies To

FPCArray


FPCArray.Publishing Property

Gets a reference to the array's publishing configuration object.

VBScript Syntax[VBScript]

[ oFPCPublishing = ] = FPCArray.Publishing

C++ Syntax[C++]

HRESULT get_Publishing(
  IFPCPublishing **poFPCPublishing
);

Parameters

oFPCPublishing
A reference to an FPCPublishing object.

The property is read-only.

Applies To

FPCArray


FPCArray.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCArray.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCArray


FPCArray.Restore Method

Reads the array's information from a file.

VBScript Syntax[VBScript]

FPCArray.Restore( sFileName, bValidateServers )

C++ Syntax[C++]

HRESULT Restore(
  BSTR sFileName,
  VARIANT_BOOL bValidateServers
);

Parameters

sFileName
A string that specifies the name of the file that contains a backup of the array information. The restore operation copies the information in that file to the current array.
bValidateServers
A Boolean value that specifies whether to check that the BIF backup file and the current array, which will be elimiated during the restore operation, have the same list of servers. The default value for this parameter is TRUE. If the lists of servers differ, the following error is returned: E_SERVER_LIST_MISMATCH_IN_BACKUP_FILE = 0x800403a4, "The given file contains different servers than the current array configuration".

Remarks

If you perform a restore from a remote computer, the path you provide should be local to the server for example, c:\Backups\MyBackup.bif. The server computer will resolve the path. Do not provide a path that is relative to the remote administration computer.

Applies To

FPCArray


FPCArray.Save Method

Saves the array configuration to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCArray.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCArray


FPCArray.SendRestartNotification Method

Gets a list of services that must be restarted, and sets a flag under each server for each service to be restarted. The ISA control service reacts to these flags and restarts the affected service when they change. You can use this method to restart the Firewall service, the Web proxy service, or both.

VBScript Syntax[VBScript]

FPCArray.SendRestartNotification( Services )

C++ Syntax[C++]

HRESULT SendRestartNotification (
  FpcServices Services
);

Parameters

Services
Specifies the services to be restarted. Can have a value from the FpcServices enumerated type.

The property is read-only.

Applies To

FPCArray


FPCArray.Servers Property

Gets a collection of all ISA servers in this array. This property can be used in turn to access all the properties of each individual server.

VBScript Syntax[VBScript]

[ collFPCServers = ] FPCArray.Servers

C++ Syntax[C++]

HRESULT get_Servers(
  IFPCServers **pcollFPCServers
);

Parameters

collFPCServers
Reference to an FPCServers collection.

The property is read-only.

Example

The following code uses the Servers property to return the name of an individual server.

Dim objFPC As New FPCLib.FPC
Dim serverName As String
Dim objFPCArray As FPCArray
Set objFPCArray = objFPC.Arrays(1)
serverName = objFPCArray.Servers(1).Name

Applies To

FPCArray

See Also

FPCServer


FPCArray.SetSecurityDescriptor Method

Sets the security descriptor for the array. For more information, see the FPCSecurityDescriptor object.

VBScript Syntax[VBScript]

FPCArray.SetSecurityDescriptor( lSecurityInfo, scope, vSecurityDescriptor )

C++ Syntax[C++]

HRESULT SetSecurityDescriptor (
  LONG lSecurityInfo,
  FpcSecurityScope scope,
  VARIANT vSecurityDescriptor
);

Parameters

lSecurityInfo
Long value that specifies security information.
scope
Specifies whether the security descriptor is for an array, for a signaled alert session, or for sessions . It can have the value fpcSingleArrayScope, fpcAlertsScope, or fpcSessionsScope from the FPCSecurityScope enumerated type.
vSecurityDescriptor
Variant that can be either a reference to an FPCSecurityDescriptor object, or a pointer to a Win32 security descriptor in self-relative format. For more information on Win32 security descriptors, see MSDN.

Remarks

This method makes use of related Windows functionality. For more information, see SetSecurityInfo in MSDN.

Applies To

FPCArray


FPCArray.SiteName Property

Gets the FPCArray object's site name.

VBScript Syntax[VBScript]

[ sSite = ] FpcArray.SiteName

C++ Syntax[C++]

HRESULT get_SiteName(
  BSTR *sSite
);

Parameters

sSite
String that specifies the FPCArray object's site name.
This property is read-only.

Applies To

FPCArray


FPCArray.Type Property

Gets the array's type, either array or stand-alone server.

VBScript Syntax[VBScript]

[ Type = ] FPCArray.Type

C++ Syntax[C++]

HRESULT get_Type(
  FpcArrayType *pType
);

Parameters

Type
Gets the array type. This can have a value from the FpcArrayType enumerated type.

Applies To

FPCArray


FPCArray.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCArray object's storage. The VendorParametersSets property allows third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCArray.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCArray


FPCArrays Collection

The FPCArrays collection provides access to a collection of FPCArray objects. Individual servers and individual server properties are accessed through each FPCArray object.

For multiple examples of using the FPCArrays collection, see ISA Administration Scripting.

FPCArrays is a property of the FPC root object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCArrays interface.

Methods

The following table lists the methods of the FPCArrays collection.

Method | Description
Add | Adds a new array to the collection. Unlike other ISA COM object Add methods, this takes place without calling a Save method.
GetContainingArray | Returns the current containing array.
Item | Returns the array object specified by the integer parameter of this method.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an array from the collection. Unlike other ISA COM object Remove methods, this takes place without calling a Save method

Properties

The following table lists the properties of the FPCArrays collection.

Property | Description
Count | Gets the number of array objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrays.Add Method

Adds a new array to the collection.

Note Unlike other ISA COM object Add methods, the addition of an array takes place without calling a Save method.

This method is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

VBScript Syntax[VBScript]

[oFPCArray = ] FPCArrays.Add( sName, sDomainName, sSiteName, lComponents, ArrayToClone bUseDefaultPolicySettings, PolicyUsedFlag, sPolicy )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  BSTR sDomainName,
  BSTR sSiteName,
  LONG lComponents,
  IDispatch *pArrayToClone,
  VARIANT_BOOL bUseDefaultPolicySettings,
  FpcPolicyUsed PolicyUsedFlag,
  BSTR sPolicy,
  IFPCArray **ppoFPCArray
);

Parameters

sName
The name of the array.
sDomainName
Optional. String that specifies the domain name in which to create the array.
sSiteName
Required. Name of FPCArray object to add.
lComponents
Long value that specifies the component flags, using values from the FpcComponents enumerated type.
bUseDefaultPolicySettings
Boolean value that specifies whether the default policy settings are used. If FALSE, the policy is configured using the PolicyUsedFlag and sPolicy parameters. This parameter is ignored if the ArraytoClone parameter is not NULL because the configuration is copied from the specified array.
PolicyUsedFlag
The policy that is used. It can have a value from the FpcPolicyUsed enumerated type. Has a default value of fpcEnterprisePolicyUsed. This parameter is meaningless if bUseDefaultPolicySettings is set to TRUE. This parameter is ignored if the ArraytoClone parameter is not NULL because the configuration is copied from the specified array.
sPolicy
String value specifying the name of the policy to use. This parameter is meaningless when only array policy is used, or if bUseDefaultPolicySettings is set to TRUE. This parameter is ignored if the ArraytoClone parameter is not NULL because the configuration is copied from the specified array.
ArrayToClone
Optional. Array name from which to copy the configuration.

Return Value

oFPCArray
Reference to the added FPCArray object.

Applies To

FPCArrays Collection


FPCArrays.Count Property

Gets the number of array objects within the FPCArrays collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCArrays.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCArray objects.

The property is read-only.

Applies To

FPCArrays


FPCArrays.GetContainingArray Method

Returns the array that contains the current computer. Assume, for example, that there are two arrays, Arr1 and Arr2. Arr1 contains two computers, a and b. Arr2 contains computer c. If you call GetContainingArray on computer a, the method returns Arr1. If you call GetContainingArray on computer c, the method returns Arr2.

VBScript Syntax[VBScript]

[ oFPCArray = ] FPCArrays.GetContainingArray()

C++ Syntax[C++]

HRESULT GetContainingArray(
  IFPCArray **poFPCArray
);

Parameters

oFPCArray
Reference to the containing FPCArray object.

Example

The following code example retrieves the name of the current containing array by means of the GetContainingArray method.

Dim objFPC As New FPCLib.FPC
Dim ContainingArray As String
Dim objFPCArrays As FPCArrays
Set objFPCArrays = objFPC.Arrays
ContainingArray = objFPCArrays.GetContainingArray.Name

Applies To

FPCArrays


FPCArrays.Item Method

Gets an FPCArray object from the collection. The object is specified by the required integer parameter.

VBScript Syntax[VBScript]

[ vItem = ] FPCArrays.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCArray **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCArray; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCArrays


FPCArrays.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCArrays.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCArrays


FPCArrays.Remove Method

Removes the specified array from the collection.

Note Unlike other ISA COM object Add methods, the removal of an array takes place without calling a Save method.

VBScript Syntax[VBScript]

FPCArrays.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the FPCArray object to remove.

Applies To

FPCArrays


FPCArrayPolicy Object

The FPCArrayPolicy object stores the topology of the ISA configuration. You can use this object to retrieve the access policy properties, consisting of IP packet filters, protocol rules, and site and content rules, and the Web proxy properties, valid for the current server array. This object does not include the publishing rules of an array policy.

The FPCArrayPolicy object is a property of the FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCArrayPolicy interface.

Methods

The following table lists the methods of the FPCArrayPolicy object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCArrayPolicy object.

Property | Description
IpPacketFilters | Gets a collection of IP packet filters in this array.
ProtocolRules | Gets a collection of the protocol rules.
SiteAndContentRules | Gets a collection of all site and content rules in this array.
WebProxy | Gets the FPCWebProxy object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrayPolicy.IpPacketFilters Property

Gets a collection of IP packet filters on this server.

VBScript Syntax[VBScript]

[ collFPCIpPacketFilters = ] FPCArrayPolicy.IpPacketFilters

C++ Syntax[C++]

HRESULT get_IpPacketFilters(
  IFPCIpPacketFilters **pcollFPCIpPacketFilters
);

Parameters

collFPCIpPacketFilters
Reference to an FPCIpPacketFilters collection.

The property is read-only.

Applies To

FPCArrayPolicy


FPCArrayPolicy.ProtocolRules Property

Gets a collection of the protocol rules.

VBScript Syntax[VBScript]

[ collFPCProtocolRules = ] FPCArrayPolicy.ProtocolRules

C++ Syntax[C++]

HRESULT get_ProtocolRules(
  IFPCProtocolRules **pcollFPCProtocolRules
);

Parameters

collFPCProtocolRules
Reference to the FPCProtocolRules collection.

The property is read-only.

Applies To

FPCArrayPolicy

See Also

FPCProtocolRule


FPCArrayPolicy.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCArrayPolicy.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCArrayPolicy


FPCArrayPolicy.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCArrayPolicy.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCArrayPolicy


FPCArrayPolicy.SiteAndContentRules Property

Gets a collection of all site and content rules in this array.

VBScript Syntax[VBScript]

[ collFPCSiteAndContentRules = ] FPCArrayPolicy.SiteAndContentRules

C++ Syntax[C++]

HRESULT get_SiteAndContentRules(
  IFPCSiteAndContentRules **pcollFPCSiteAndContentRules
);

Parameters

collFPCSiteAndContentRules
Reference to an FPCSiteAndContentRules collection.

The property is read-only.

Applies To

FPCArrayPolicy

See Also

FPCSiteAndContentRule


FPCArrayPolicy.WebProxy Property

Gets the FPCWebProxy object.

VBScript Syntax[VBScript]

[ oFPCWebProxy = ] FPCArrayPolicy.WebProxy

C++ Syntax[C++]

HRESULT get_WebProxy(
  IFPCWebProxy **poFPCWebProxy
);

Parameters

oFPCWebProxy
Reference to the FPCWebProxy object.

The property is read-only.

Applies To

FPCArrayPolicy


FPCArrayPolicyConfig Object

The FPCArrayPolicyConfig object is used to associate an enterprise policy with an array. This object is a member of the FPCArrayPolicyConfigs collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCArrayPolicyConfig interface.

Methods

The following table lists the methods of the FPCArrayPolicyConfig object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetPolicy | Sets the values of the PolicyUsedFlag and PolicyName properties.

Properties

The following table lists the properties of the FPCArrayPolicyConfig object.

Property | Description
AllowPublishing | Gets or sets a Boolean value that allows definition of publishing rules in an array.
ArrayName | Gets the array name to which this enterprise policy applies.
ForcePacketFiltering | Gets or sets a Boolean value that forces IP packet filtering in an array.
PolicyName | Gets the enterprise-policy object associated with the given array.
PolicyUsedFlag | Gets a value that specifies whether the array uses local and/or enterprise policy.
UseDefaults | Gets or sets the UseDefaults value to which this object applies. When UseDefaults is set to TRUE, the array uses the default policy configuration set in the FPCEnterprise object.
VendorParametersSets | Gets a reference to an object that stores vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrayPolicyConfig.AllowPublishing Property

Gets or sets a Boolean value that allows definition of publishing rules in an array.

VBScript Syntax[VBScript]

FPCArrayPolicyConfig.AllowPublishing [ = bAllowPublishing ]

C++ Syntax[C++]

HRESULT get_AllowPublishing(
  VARIANT_BOOL *pbAllowPublishing
);

HRESULT put_AllowPublishing(
  VARIANT_BOOL bAllowPublishing
);

Parameters

bAllowPublishing
A Boolean value that determines whether definition of publishing rules is allowed in an array.

This property is read-write.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.ArrayName Property

Gets the array name to which this enterprise policy applies.

VBScript Syntax[VBScript]

[ sName = ]FPCArrayPolicyConfig.ArrayName

C++ Syntax[C++]

HRESULT get_ArrayName(
  BSTR *psName
);

Parameters

sName
String that specifies the parameter name for which to retrieve the value.

The property is read-only.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.ForcePacketFiltering Property

Gets or sets a Boolean value that forces packet filtering in an array.

VBScript Syntax[VBScript]

FPCArrayPolicyConfig.ForcePacketFiltering [ = bForce ]

C++ Syntax[C++]

HRESULT get_ForcePacketFiltering(
  VARIANT_BOOL *pbForce
);

HRESULT put_ForcePacketFiltering(
  VARIANT_BOOL bForce
);

Parameters

bForce
Boolean value that determines whether IP packet filtering is forced in an array.

The property is read-write.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.PolicyName Property

Gets the name of the enterprise policy that is associated with the array.

VBScript Syntax[VBScript]

[ sName = ] FPCArrayPolicyConfig.PolicyName

C++ Syntax[C++]

HRESULT get_PolicyName(
  BSTR *psName
);

Parameters

sName
String that specifies the policy name.

The property is read only.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.PolicyUsedFlag Property

Gets a value that specifies whether the array uses its local and/or enterprise policy.

VBScript Syntax[VBScript]

[ PolicyUsed = ] FPCArrayPolicyConfig.PolicyUsedFlag

C++ Syntax[C++]

HRESULT get_PolicyUsedFlag(
  FpcPolicyUsed *pPolicyUsed
);

Parameters

PolicyUsed
The policy that is used. It can have a value from the FpcPolicyUsed enumerated type.

The property is read only, but can be set in SetPolicy.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCArrayPolicyConfig.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCArrayPolicyConfig.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.SetPolicy Method

Sets the values of the PolicyUsedFlag and PolicyName properties.

Note You can only set the PolicyUsedFlag to fpcArrayPolicyUsed when you first add a new array by using the Arrays.Add method. In an existing array, you can only change the value from fpcEnterprisePolicyUsed to fpcArrayAndEnterprisePoliciesUsed, and from fpcArrayAndEnterprisePoliciesUsed to fpcEnterprisePolicyUsed.

You need to set FPCArrayPolicyConfig.UseDefaults = FALSE before you update the policy.

VBScript Syntax[VBScript]

FPCArrayPolicyConfig.SetPolicyP( Flag, sPolicy )

C++ Syntax[C++]

HRESULT SetPolicy(
  FpcPolicyUsed Flag,
  BSTR sPolicy
);

Parameters

Flag
A value that specifies whether an array uses local and/or enterprise policy. It can have a value from the FpcPolicyUsed enumerated type.
sPolicy
A string that specifies the name of the policy. It can be empty to indicate that the array is not using an enterprise policy.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.UseDefaults Property

Gets or sets the UseDefaults value to which the FPCArrayPolicyConfig object applies. When UseDefaults is set to TRUE, the array uses the default policy configuration set in the FPCEnterprise object.

VBScript Syntax[VBScript]

FPCArrayPolicyConfig.UseDefaults [ = bUseDefaults ]

C++ Syntax[C++]

HRESULT get_UseDefaults(
  VARIANT_BOOL *pbUseDefaults
);

HRESULT put_UseDefaults(
  VARIANT_BOOL bUseDefaults
);

Parameters

bUseDefaults
A Boolean value that specifies whether to use the default settings of the object.

The property is read-write.

Note You cannot define a local policy configuration when bUseDefaults equals TRUE.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfig.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up with all other ISA objects.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCArrayPolicyConfig.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCArrayPolicyConfig


FPCArrayPolicyConfigs Collection

The FPCArrayPolicyConfigs collection provides access to a group of FPCArrayPolicyConfig objects. This collection therefore contains the policy collections of all ISA arrays

FPCArrayPolicyConfigs is a property of the FPCEnterprise object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCArrayPolicyConfigs interface.

Methods

The following table lists the methods of the FPCArrayPolicyConfigs collection.

Method | Description
Item | Returns the FPCArrayPolicyConfig object specified by the integer parameter of this method.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCArrayPolicyConfigs collection.

Property | Description
Count | Gets the number of policy objects in the collection.
VendorParametersSets | Used to programmatically access vendor-specific data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCArrayPolicyConfigs.Count Property

Gets the number of FPCArrayPolicyConfig objects within the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCArrayPolicyConfigs.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCArrayPolicyConfig objects.

The property is read-only.

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.Item Method

Returns an FPCArrayPolicyConfig object from the collection. The object is specified by the required integer parameter.

VBScript Syntax[VBScript]

[ vItem = ] FPCArrayPolicyConfigs.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCArrayPolicyConfig **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCArrayPolicyConfig; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCArrayPolicyConfigs.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCArrayPolicyConfigs.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCArrayPolicyConfigs


FPCArrayPolicyConfigs.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection will be backed up from the Active Directory with all other FPC objects.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCArrayPolicyConfigs.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCArrayPolicyConfigs


FPCAutoDial Object

The FPCAutoDial object represents an automatic-dial state (enabled or disabled) and phone-book entry. A network can be configured so that it automatically dials out of the network for specific requests. The dialup entry provides information on how to dial.

This object is a property of the FPCRoutingRule, FPCPrimaryRoute, FPCBackupRoute, and FPCFirewallChaining objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCAutoDial interface.

Methods

The following table lists the methods of the FPCAutoDial object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCAutoDial object.

Property | Description
EnableAutoDial | Gets or sets if the auto dial function is enabled.
VendorParametersSets | Not implemented for this object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCAutoDial.EnableAutoDial Property

Gets or sets if auto dial is enabled.

VBScript Syntax[VBScript]

FPCAutoDial.EnableAutoDial[ = bEnabled ]

C++ Syntax[C++]

HRESULT get_EnableAutoDial(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_EnableAutoDial(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
A Boolean value that specifies if auto dial is enabled.

The property is read-write.

Applies To

FPCAutoDial


FPCAutoDial.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCAutoDial.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCAutoDial


FPCAutoDial.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCAutoDial.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCAutoDial


FPCBackupRoute Object

The FPCBackupRoute object represents the backup route entity, which is either a single ISA server or an array of ISA servers. This object is a property of the FPCPrimaryRoute object, which you can access through the FPCPrimaryRoute.BackupRoute property.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCBackupRoute interface.

Methods

The following table lists the methods of the FPCBackupRoute object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetAutoPollConfig | Sets whether proxy polling of the upstream proxy server or array for membership information is enabled.
SetServerAndPort | Sets the server and port for the entity.

Properties

The following table lists the properties of the FPCBackupRoute object.

Property | Description
AuthenticationEnabled | Gets or sets whether the use of authentication in upstream routing is enabled.
AuthenticationType | Gets or sets the type of authentication that the entity uses.
AutoDialOut | Gets a reference to an FPCAutoDial object that represents the automatic-dial settings.
AutomaticPollConfig | Gets whether proxy polling of the upstream proxy or array for membership information is enabled.
BackupRouteType | Gets or sets the backup route type.
Credentials | Gets an FPCCredentials object used to read and write credentials information. This information is used if a proxy server needs to authenticate with an upstream proxy server.
PollAtURL | Gets the URL, usually at the upstream proxy, at which to poll for the array configuration information. This property is valid if the AutomaticPollConfig property is enabled.
RouteServerName | Gets the name of the ISA Server or array.
RouteServerPort | Gets the port that this entity is listening on.
RouteServerSSLPort | Gets the port for listening on a secure channel.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBackupRoute.AuthenticationEnabled Property

Gets or sets whether the use of downstream client authentication in upstream routing is enabled.

VBScript Syntax[VBScript]

FPCBackupRoute.AuthenticationEnabled [= bEnabled ]

C++ Syntax[C++]

HRESULT get_AuthenticationEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_AuthenticationEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether authentication is enabled.

The property is read-write.

Applies To

FPCBackupRoute


FPCBackupRoute.AuthenticationType Property

Gets or sets the type of authentication that the entity uses.

VBScript Syntax[VBScript]

FPCBackupRoute.AuthenticationType [ = AuthType ]

C++ Syntax[C++]

HRESULT get_AuthenticationType(
  FpcAuthType *pAuthType
);

HRESULT put_AuthenticationType(
  FpcAuthType AuthType
);

Parameters

AuthType
Authentication type. It can have a value from the FpcAuthType enumerated type.

The property is read-write.

Remarks

Basic authentication (fpcUiAuthBasic) is not encrypted.

Applies To

FPCBackupRoute


FPCBackupRoute.AutoDialOut Property

Gets a reference to an FPCAutoDial object that represents the automatic-dial settings.

VBScript Syntax[VBScript]

[ oFPCAutoDial = ] FPCBackupRoute.AutoDialOut

C++ Syntax[C++]

HRESULT get_AutoDialOut(
  IFPCAutoDial **oFPCAutoDial
);

Parameters

oFPCAutoDial
Refrence to an FPCAutoDial object that represents the auto dial settings.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.AutomaticPollConfig Property

Gets whether polling of the upstream proxy or array is enabled for membership information. With polling, the upstream server will supply array information.

VBScript Syntax[VBScript]

FPCBackupRoute.AutomaticPollConfig [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_AutomaticPollConfig(
  VARIANT_BOOL *pbEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether proxy polling is enabled.

The property is read-only. It can be modified through the SetAutoPollConfig method.

Applies To

FPCBackupRoute


FPCBackupRoute.BackupRouteType Property

Gets or sets whether there is a backup route, and whether it is direct to the Internet or through an upstream proxy server.

VBScript Syntax[VBScript]

FPCBackupRoute.BackupRouteType [ = RouteType ]

C++ Syntax[C++]

HRESULT get_BackupRouteType(
  FpcBackupRouteType *pRouteType
);

HRESULT put_BackupRouteType(
  FpcBackupRouteType RouteType
);

Parameters

RouteType
Route Type. It can have the value fpcBackupArrayConfiguration or fpcBackupEnterpriseConfiguration from the FpcBackupRouteType enumerated type. The value fpcBackupEnterpriseConfiguration is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

The property is read-write.

Applies To

FPCBackupRoute


FPCBackupRoute.Credentials Property

Gets an FPCCredentials object to read and write credential information. An ISA server uses this information if it needs to authenticate a connection to an upstream server.

VBScript Syntax[VBScript]

[ oFPCCredentials = ] FPCBackupRoute.Credentials

C++ Syntax[C++]

HRESULT get_Credentials(
  IFPCCredentials **oFPCCredentials
);

Parameters

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.PollAtURL Property

Gets the URL, usually at the upstream proxy, to poll for the array configuration information. This property is valid if the AutomaticPollConfig property is enabled.

VBScript Syntax[VBScript]

[ sURL = ]FPCBackupRoute.PollAtURL

C++ Syntax[C++]

HRESULT get_PollAtURL(
  BSTR *psURL
);

Parameters

sURL
String that specifies the URL.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCBackupRoute.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCBackupRoute


FPCBackupRoute.RouteServerName Property

Gets the name of the ISA server or array.

VBScript Syntax[VBScript]

[ sName = ] FPCBackupRoute.RouteServerName

C++ Syntax[C++]

HRESULT get_RouteServerName(
  BSTR *psName
);

Parameters

sName
String that specifies the name of the ISA server or array.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.RouteServerPort Property

Gets the port on which the ISA server or array of ISA servers is listening.

VBScript Syntax[VBScript]

[ lPort = ] FPCBackupRoute.RouteServerPort

C++ Syntax[C++]

HRESULT get_RouteServerPort(
  long *plPort
);

Parameters

lPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.RouteServerSSLPort Property

Gets the port for listening on a secure channel.

VBScript Syntax[VBScript]

[ lSSLPort = ] FPCBackupRoute.RouteServerSSLPort

C++ Syntax[C++]

HRESULT get_RouteServerSSLPort(
  long *plSSLPort
);

Parameters

lSSLPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-only.

Applies To

FPCBackupRoute


FPCBackupRoute.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCBackupRoute.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCBackupRoute


FPCBackupRoute.SetAutoPollConfig Method

Sets whether polling of the upstream ISA server or array is enabled for membership information.

VBScript Syntax[VBScript]

FPCBackupRoute.SetAutoPollConfig (fSetAuto, sAutoPollUrl)

C++ Syntax[C++]

HRESULT SetAutoPollConfig(
  VARIANT_BOOL fSetAuto,
  BSTR sAutoPollUrl
);

Parameters

fSetAuto
Boolean expression that specifies whether automatic configuration is to be enabled.
sAutoPollUrl
Optional. String that specifies the URL, usually at the upstream proxy, to poll for the array configuration information. If fSetAuto is set to TRUE, this parameter must hold a valid URL; otherwise, sAutoPollUrl is ignored.

Applies To

FPCBackupRoute


FPCBackupRoute.SetServerAndPort Method

Sets the server and port for the entity.

VBScript Syntax[VBScript]

FPCBackupRoute.SetServerAndPort( sServerName, lPort, lSSLPort)

C++ Syntax[C++]

HRESULT SetServerAndPort(
  BSTR sServerName,
  long lPort,
  long lSSLPort
);

Parameters

sServerName
String that specifies the name of the server.
lPort
Long value that specifies the port number that the server listens on. It can be a value from 1 to 65535.
lSSLPort
Long value that specifies the port number that the server listens on for SSL connections. It can be a value from 1 to 65535.

Applies To

FPCBackupRoute


FPCBandwidthPriority Object

The FPCBandwidthPriority object represents a single bandwidth priority entry. You can modify internal or external bandwidth with this object. Bandwidth priorities are used by the rules to define bandwidth resource allocation among competing requests.

ISA administrators control the amount of bandwidth that is allocated for any specific Internet request. You can configure External bandwidth priority, the bandwidth priority allocated for communication with the Internet, and Internal bandwidth priority, the bandwidth priority allocated for communication among computers behind the ISA server.

This object is a member of the FPCBandwidthPriorities collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCBandwidthPriority interface.

Methods

The following table lists the methods of the FPCBandwidthPriority object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCBandwidthPriority object.

Property | Description
BandwidthExternalWeight | Gets or sets the bandwidth for external traffic defined by the FPCBandwidthPriority object.
BandwidthInternalWeight | Gets or sets bandwidth for internal traffic defined by the FPCBandwidthPriority object.
Description | Gets or sets the description of the FPCBandwidthPriority object.
Name | Gets or sets the name of the FPCBandwidthPriority object.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthPriority.BandwidthExternalWeight Property

Gets or sets the bandwidth for external traffic defined by the bandwidth priority.

VBScript Syntax[VBScript]

FPCBandwidthPriority.BandwidtExternalWeight [ = lBandwidthExternalWeight ]

C++ Syntax[C++]

HRESULT get_BandwidthExternalWeight(
  long *plBandwidthExternalWeight
);

HRESULT put_BandwidthExternalWeight(
  long lBandwidthExternalWeight
);

Parameters

lBandwidthExternalWeight
Long value that specifies the weight of the bandwidth priority (0-200).

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.BandwidthInternalWeight Property

Gets or sets bandwidth for internal traffic defined by the bandwidth priority.

VBScript Syntax[VBScript]

FPCBandwidthPriority.BandwidtInternalWeight [ = lBandwidthInternalWeight ]

C++ Syntax[C++]

HRESULT get_BandwidthInternalWeight(
  long *plBandwidthInternalWeight
);

HRESULT put_BandwidthInternalWeight(
  long lBandwidthInternalWeight
);

Parameters

lBandwidthInternalWeight
Long value that specifies the internal bandwidth of the bandwidth priority (0-200).

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Description Property

Gets or sets the description of the bandwidth priority.

VBScript Syntax[VBScript]

FPCBandwidthPriority.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the bandwidth priority.

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Name Property

Gets or sets the name of the bandwidth priority.

VBScript Syntax[VBScript]

FPCBandwidthPriority.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the bandwidth priority.

The property is read-write.

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Refresh Method

Reads the object's data from persistent storage, discarding any changes to the data that were not saved.

VBScript Syntax[VBScript]

FPCBandwidthPriority.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCBandwidthPriority.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCBandwidthPriority


FPCBandwidthPriority.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCBandwidthPriority object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCBandwidthPriority.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthPriority


FPCBandwidthPriorities Collection

The FPCBandwidthPriorities collection represents a group of FPCBandwidthPriority objects. Bandwidth priorities are used by the rules to define bandwidth resource allocation among competing requests. You can configure:

  • External bandwidth, the bandwidth priority allocated for communication with the Internet.
  • Internal bandwidth, the bandwidth priority allocated for communication between computers behind the ISA Server.

The FPCBandwidthPriorities collection is a property of the FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCBandwidthPriorities interface.

Methods

The following table lists the methods of the FPCBandwidthPriorities collection.

Method | Description
Add | Creates a new FPCBandwidthPriority object in the collection and returns a reference to it.
Item | Retrieves the given FPCBandwidthPriority object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCBandwidthPriority object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCBandwidthPriorities collection.

Property | Description
Count | Gets the number of FPCBandwidthPriority objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCBandwidthPriorities collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthPriorities.Add Method

Creates a new FPCBandwidthPriority object in the collection and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCBandwidthPriority = ] FPCBandwidthPriorities.Add( sName, lBandwidthInternalWeight, lBandwidthExternalWeight )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  long lBandwidthInternalWeight,
  long lBandwidthExternalWeight,
  IFPCBandwidthPriority **ppoFPCBandwidthPriority
);

Parameters

sName
Required. String that specifies the name of the new FPCBandwidthPriority entry.
lBandwidthInternalWeight
Required. Long value that specifies the bandwidth for internal traffic defined by the new FPCBandwidthPriority entry.
lBandwidthExternalWeight
Required. Long value that specifies the bandwidth for external traffic defined by the new FPCBandwidthPriority entry.

Return Values

oFPCBandwidthPriority
Reference to an FPCBandwidthPriority object.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Count Property

Gets the number of FPCBandwidthPriority objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCBandwidthPriorities.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCBandwidthPriority objects.

The property is read-only.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Item Method

Gets the given FPCBandwidthPriority object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCBandwidthPriorities.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCBandwidthPriority **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCBandwidthPriority; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCBandwidthPriorities.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Remove Method

Removes an FPCBandwidthPriority object from the collection.

VBScript Syntax[VBScript]

FPCBandwidthPriorities.Remove( vItem )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vItem
);

Parameters

vItem
Required. One-based index of the object to remove.

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCBandwidthPriorities.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCBandwidthPriorities


FPCBandwidthPriorities.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCBandwidthPriorities object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCBandwidthPriorities.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthPriorities


FPCBandwidthRule Object

The FPCBandwidthRule object represents a single bandwidth rule. A bandwidth rule defines the bandwidth to be allocated for various types of requests. You define a bandwidth rule by using ISA's policy elements and by establishing the requests to which the rule will apply. This object is a member of the FPCBandwidthRules collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCBandwidthRule interface.

Methods

The following table lists the methods of the FPCBandwidthRule object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetAppliesAlways | Sets the rule to apply always, regardless of the ScheduleTemplateUsed property.
SetBandwidthPriority | Sets the bandwidth rule to use windows quality of service (QOS) or a specific bandwidth priority.
SetDestination | Sets the destinations to which the rule applies.
SetSchedule | Sets the value of the schedule that applies to this rule.

Properties

The following table lists the properties of the FPCBandwidthRule object.

Property | Description
AppliesAlways | Gets whether the rule applies at all times.
AppliesToAccounts | Gets the collection of accounts to which the rule applies.
AppliesToContentMethodType | Gets or sets the selection of content to which the rule applies.
AppliesToDestination | Gets the type of destination to which the rule applies.
AppliesToMethod | Gets or sets the method used for deciding rule applicability.
BandwidthPriorityUsed | Gets the name of the FPCBandwidthPriority object that is used to define the bandwidth applicable to this rule.
ClientAddressSetsExcluded | Gets the collection of client address sets to which the rule does not apply.
ClientAddressSetsUsed | Gets the collection of client address sets to which the rule applies.
ContentGroupsUsed | Represents a collection of the content groups to which the rule applies.
Description | Gets or sets the description of the set.
DestinationSetUsed | Gets the FPCRefs collection used to define the destination to which the rule applies.
Enabled | Gets or sets whether the rule is enabled.
IsDefault | Gets whether the rule is pre-installed and cannot be deleted.
Name | Gets or sets the name of the bandwidth rule.
Order | Gets the filter's order.
ProtocolSelectionMethod | Gets or sets whether the rule applies to all IP traffic, all protocols, or specified protocols.
ScheduleUsed | Gets or sets the name of the schedule template object used to define the times when the rule applies.
SpecifiedProtocols | Gets the FPCRefs collection used by the rule.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the object's storage.
WindowsQoSEnabled | Gets whether the rule uses the defualt windows QOS bandwidth.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthRule.AppliesAlways Property

Gets whether the rule applies at all times.

VBScript Syntax[VBScript]

[ bApplies = ] FPCBandwidthRule.AppliesAlways

C++ Syntax[C++]

HRESULT get_AppliesAlways(
  VARIANT_BOOL *pbApplies
);

Parameters

bApplies
A Boolean value that specifies whether the rule applies at all times.

The property is read only. It can be set to TRUE by calling the SetAppliesAlways method. Choosing a schedule by calling ScheduleUsed will set the property to FALSE.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToAccounts Property

Gets the collection of accounts to which the rule applies. The collection of FPCAccount objects contains definintions of accounts for users or groups of users.

VBScript Syntax[VBScript]

[ collFPCAccounts = ] FPCBandwidthRule.AppliesToAccounts

C++ Syntax[C++]

HRESULT get_AppliesToAccounts(
  IFPCAccounts **pcollFPCAccounts
);

Parameters

collFPCAccounts
Reference to the FPCAccounts collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToContentMethodType Property

Gets or sets the selection of content to which the rule applies.

VBScript Syntax[VBScript]

FPCBandwidthRule.AppliesToContentMethodType [ = Applies ]

C++ Syntax[C++]

HRESULT get_AppliesToContentMethodType(
  FpcAppliesToContentMethodType *pApplies
);

HRESULT put_AppliesToContentMethodType(
  FpcAppliesToContentMethodType Applies
);

Parameters

Applies
Applies to content. It can have a value from the FpcAppliesToContentMethodType enumerated type.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToDestination Property

Gets the type of destination to which the rule applies.

VBScript Syntax[VBScript]

[ DestinationSelection = ] FPCBandwidthRule.AppliesToDestination

C++ Syntax[C++]

HRESULT get_AppliesToDestination(
  FpcDestinationSelection *pDestinationSelection
);

Parameters

DestinationSelection
Type of destination to which the rule applies. It can have a value from the FpcDestinationSelection enumerated type.

The property is read-only. It can be set by using the SetDestination method.

Applies To

FPCBandwidthRule


FPCBandwidthRule.AppliesToMethod Property

Gets or sets how rules are applied, based on request origin.

VBScript Syntax[VBScript]

FPCBandwidthRule.AppliesToMethod [ = AppliesToType]

C++ Syntax[C++]

HRESULT get_AppliesToMethod(
  FpcAppliesToType *pAppliesToType
);

HRESULT put_AppliesToMethod(
  FpcAppliesToType AppliesToType
);

Parameters

AppliesToType
Applicability method. It can have a value from the FpcAppliesToType enumerated type.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.BandwidthPriorityUsed Property

Gets the name of the bandwidth priority object used to define the bandwidth that applies to this rule. You set the bandwidth priority using the SetBandwidthPriority method.

VBScript Syntax[VBScript]

[ sPriority = ]FPCBandwidthRule.BandwidthPriorityUsed

C++ Syntax[C++]

HRESULT get_BandwidthPriorityUsed(
  BSTR *psPriority
);

Parameters

sPriority
String that specifies the name of the bandwidth priority object.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ClientAddressSetsExcluded Property

Gets the collection of client address sets to which the rule does not apply. This property is useful only when the ClientAddressSetsUsed property is not empty. It allows you to design a rule that applies to one set of clients but excludes another set of clients.

ClientAddressSetsExcluded is designed to allow exceptions to the specified collection of client address sets.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCBandwidthRule.ClientAddressSetsExcluded

C++ Syntax[C++]

HRESULT get_ClientAddressSetsExcluded(
  IFPCRefs **pcollFPCRefs
);

Return Values

collFPCRefs
Reference to the FPCRefs collection that contains references to the client address sets that are excluded.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ClientAddressSetsUsed Property

Gets the collection of client address sets to which the rule applies.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCBandwidthRule.ClientAddressSetsUsed

C++ Syntax[C++]

HRESULT get_ClientAddressSetsUsed(
  IFPCRefs **pcollFPCRefs
);

Return Values

collFPCRefs
Reference to the FPCRefs collection that contains references to the client address sets that are used.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ContentGroupsUsed Property

Gets the collection of content groups to which the rule applies.

VBScript Syntax[VBScript]

[ collContentGroupsUsed = ] FPCBandwidthRule.ContentGroupsUsed

C++ Syntax[C++]

HRESULT get_ContentGroupsUsed(
  IFPCRefs **pcollContentGroupsUsed
);

Return Values

collContentGroupsUsed
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Description Property

Gets or sets the description of the set.

VBScript Syntax[VBScript]

FPCBandwidthRule.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  IFPCRefs **psDescription
);

HRESULT put_Description(
  IFPCRefs sDescription
);

Parameters

sDescription
String that specifies the description of the bandwidth rule.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.DestinationSetUsed Property

Gets the FPCRef object used to define the destination to which the rule applies.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCBandwidthRule.DestinationSetUsed

C++ Syntax[C++]

HRESULT get_DestinationSetUsed(
  IFPCRef **poFPCRef
);

Parameters

oFPCRef
The FPCRef object that is used to define the destination to which the rule applies.

The property is read-only. It can be set by using the SetDestination method.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Enabled Property

Gets or sets whether the rule is enabled.

VBScript Syntax[VBScript]

FPCBandwidthRule.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether the rule is enabled.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.IsDefault Property

Gets whether the rule is a preinstalled rule that cannot be deleted. You cannot change the properties of the default rule.

VBScript Syntax[VBScript]

[ bPreInstalled = ] FPCBandwidthRule.IsDefault

C++ Syntax[C++]

HRESULT get_IsDefault(
  VARIANT_BOOL *pbPreInstalled
);

Parameters

bPreInstalled
A Boolean value that specifies whether the rule is preinstalled.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Name Property

Gets or sets the name of the bandwidth rule.

VBScript Syntax[VBScript]

FPCBandwidthRule.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the bandwidth rule.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Order Property

Gets the filter's order.

VBScript Syntax[VBScript]

[ lOrder = ] FPCISAPIFilter.Order

C++ Syntax[C++]

HRESULT get_Order(
  long *plOrder
);

Parameters

lOrder
Long value that specifies the order of the filter.

The property is read-only. Set the order using the FPCBandwidthRules.MoveDown and FPCBandwidthRules.MoveUp methods.

Applies To

FPCBandwidthRule


FPCBandwidthRule.ProtocolSelectionMethod Property

Gets or sets whether the rule applies to all Internet Protocol (IP) traffic or to specified protocols.

VBScript Syntax[VBScript]

FPCBandwidthRule.ProtocolSelectionMethod [ = ProtocolSelectionType ]

C++ Syntax[C++]

HRESULT get_ProtocolSelectionMethod(
  FpcProtocolSelectionType *pProtocolSelectionType
);

HRESULT put_ProtocolSelectionMethod(
  FpcProtocolSelectionType ProtocolSelectionType
);

Parameters

ProtocolSelectionType
Protocol selection type. It can have a value from the FpcProtocolSelectionType enumerated type.

The property is read-write.

Applies To

FPCBandwidthRule


FPCBandwidthRule.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCBandwidthRule.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCBandwidthRule


FPCBandwidthRule.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCBandwidthRule.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCBandwidthRule


FPCBandwidthRule.ScheduleUsed Property

Gets the FPCRef object that is used to define the times when the rule applies.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCBandwidthRule.ScheduleUsed

C++ Syntax[C++]

HRESULT get_ScheduleUsed(
  IFPCRef **poFPCRef
);

Parameters

oFPCRef
The FPCRef object that is used to define the times when the rule applies.

The property is read only. The value of this property can be set by using the SetSchedule method.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetAppliesAlways Method

Sets the rule to apply always, regardless of the value of the ScheduleUsed property.

VBScript Syntax[VBScript]

FPCBandwidthRule.SetAppliesAlways()

C++ Syntax[C++]

HRESULT SetAppliesAlways();

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetBandwidthPriority Method

Sets the bandwidth rule to use Windows quality of service (QoS) or a specific bandwidth priority.

VBScript Syntax[VBScript]

FPCBandwidthRule.SetBandwidthPriority( bIsWindowsQoS, sNewPriority )

C++ Syntax[C++]

HRESULT put_SetBandwidthPriority(
  VARIANT_BOOL bIsWindowsQoS,
  BSTR sNewPriority
);

Parameters

bIsWindowsQoS
A Boolean value that specifies whether the rule uses Windows QoS bandwidth (TRUE) or a specific bandwidth priority (FALSE).
sNewPriority
Optional. String that defines a bandwidth priority to use. Only used if bIsWindowsQoS equals FALSE.

The property is read only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetDestination Method

Sets the destinations to which the rule applies.

VBScript Syntax[VBScript]

FPCBandwidthRule.SetDestination( DestType, sDestinationSet, ItemScope )

C++ Syntax[C++]

HRESULT SetDestination (
  FpcDestinationSelection DestType,
  BSTR sDestinationSet,
  FpcItemScope ItemScope
);

Parameters

DestType
Required. Defines the type of destinations to which the rule applies. Can have a value from the FpcDestinationSelection enumerated type.
sDestinationSet
Optional. String that defines a set of destinations to use. Only used if DestType equals the value FPCDestinationSet.
ItemScope
The item scope. Can have a value from the FpcItemScope enumerated type. Has a default value of fpcArrayScope.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SetSchedule Method

Sets the value of the schedule that applies to this rule.

VBScript Syntax[VBScript]

FPCBandwidthRule.SetSchedule( sScheduleName, Scope )

C++ Syntax[C++]

HRESULT SetSchedule(
  BSTR sScheduleName,
  FpcItemScope Scope
);

Parameters

sScheduleName
String that specifies the name of the Schedule object used by this rule.
Scope
Item scope. Can be a value from the FpcItemScope enumerated type. The default value is fpcArrayScope.

Applies To

FPCBandwidthRule


FPCBandwidthRule.SpecifiedProtocols Property

Gets the FPCRefs collection that includes the specific protocols used by the rule. Only relevant if the FPCBandwidthRule.ProtocolSelectionMethod property is set to fpcSpecifiedProtocols.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCBandwidthRule.SpecifiedProtocols

C++ Syntax[C++]

HRESULT get_SpecifiedProtocols(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCBandwidthRule object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCBandwidthRule.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCBandwidthRule.WindowsQoSEnabled Property

Gets whether the rule uses the default Windows quality-of-service (QoS) bandwidth.

VBScript Syntax[VBScript]

[ bEnabled = ]FPCBandwidthRule.WindowsQoSEnabled

C++ Syntax[C++]

HRESULT get_WindowsQoSEnabled(
  VARIANT_BOOL *pbEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether the rule uses Windows QoS bandwidth.

The property is read only.

Applies To

FPCBandwidthRule


FPCBandwidthRules Collection

The FPCBandwidthRules collection provides access to a group of FPCBandwidthRule objects. This collection is a property of the FPCArrayPolicy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCBandwidthRules interface.

Methods

The following table lists the methods of the FPCBandwidthRules collection.

Method | Description
Add | Creates a new rule, adds it to the collection, and returns a reference to it.
Item | Retrieves the given FPCBandwidthRule object from the collection.
MoveDown | Moves the given rule one step down in the order of execution.
MoveUp | Moves the given rule one step up in the order of execution.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a rule object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCBandwidthRules collection.

Property | Description
Count | Gets the number of rule objects in the collection.
EnableBandwidthControl | Gets or sets whether bandwidth control is enabled.
TotalExternalBandwidth | Gets or sets the total bandwidth for external connections.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCBandwidthRules.Add Method

Creates a new rule, adds it to the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCBandwidthRule = ] FPCBandwidthRules.Add( sRuleName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sRuleName,
  IFPCBandwidthRule **ppoFPCBandwidthRule
);

Parameters

sRuleName
Required. String that specifies the name of the rule. A string of zero length (not NULL) specifies intrinsic protocols.

Return Values

oFPCBandwidthRule
Reference to the new FPCBandwidthRule object.

Applies To

FPCBandwidthRules


FPCBandwidthRules.Count Property

Gets the number of rule objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCBandwidthRules.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of rule objects.

The property is read-only.

Applies To

FPCBandwidthRules

See Also

FPCBandwidthRule


FPCBandwidthRules.EnableBandwidthControl Property

Gets or sets whether bandwidth control is enabled. Bandwidth control is an ISA Server mechanism that informs the Windows 2000 QoS packet scheduling service how to prioritize connections that pass through ISA Server.

VBScript Syntax[VBScript]

FPCBandwidthRules.EnableBandwidthControl [ = bEnabled]

C++ Syntax[C++]

HRESULT get_EnableBandwidthControl(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_EnableBandwidthControl(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean that specifies whether bandwidth control is enabled.

The property is read-write.

Applies To

FPCBandwidthRules


FPCBandwidthRules.Item Method

Retrieves the given FPCBandwidthRule object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCBandwidthRules.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCBandwidthRule **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCBandwidthRule; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCBandwidthRules


FPCBandwidthRules.MoveDown Method

Moves the given rule one step down in the order of execution.

VBScript Syntax[VBScript]

FPCBandwidthRules.MoveDown( lIndex )

C++ Syntax[C++]

HRESULT MoveDown(
  long lIndex
);

Parameters

lIndex
Required. Long value containing the index (current location in the order) of the rule to move down in the order of execution.

Applies To

FPCBandwidthRules

See Also

MoveUp


FPCBandwidthRules.MoveUp Method

Moves the given rule one step up in the order of execution.

VBScript Syntax[VBScript]

FPCBandwidthRules.MoveUp( lIndex )

C++ Syntax[C++]

HRESULT MoveUp(
  long lIndex
);

Parameters

lIndex
Required. Long value that contains the index (current location in the order) of the rule to move up in the order of execution.

Applies To

FPCBandwidthRules

See Also

MoveDown


FPCBandwidthRules.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCBandwidthRules.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCBandwidthRules


FPCBandwidthRules.Remove Method

Removes a rule object from the collection.

VBScript Syntax[VBScript]

FPCBandwidthRules.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCBandwidthRules

See Also

FPCBandwidthRule


FPCBandwidthRules.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCBandwidthRules.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCBandwidthRules


FPCBandwidthRules.TotalExternalBandwidth Property

Gets or sets the total bandwidth for connections through an external network adapter.

Bandwidth for dialup connections is set by using the FPCDialupEntry.DialupBandwidth property.

Remarks

Effective bandwidth is the actual bandwidth for a particular dial-up device (for example, a modem) or total effective network bandwidth. Microsoft Internet Security and Acceleration (ISA) Server uses the effective bandwidth that you specify as the basis for determining actual bandwidth to be assigned to a particular connection, based on the bandwidth priority specified for the rule.

The first step in determining effective bandwidth is determining the maximum effective bandwidth of the connections on the ISA Server computer or array. For frame relay networks, E1/T1 or E3/T3, the maximum effective bandwidth is determined by the Internet service provider.

VBScript Syntax[VBScript]

FPCBandwidthRules.TotalExternalBandwidth [ = lExtBandwidth]

C++ Syntax[C++]

HRESULT get_TotalExternalBandwidth(
  long *plExtBandwidth
);

HRESULT put_TotalExternalBandwidth(
  long lExtBandwidth
);

Parameters

lExtBandwidth
Long value that specifies the total external bandwidth.

The property is read-write.

Applies To

FPCBandwidthRules


FPCBandwidthRules.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCBandwidthRules collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCBandwidthRules.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCBandwidthRule


FPCCache Object

The FPCCache object is used to administer all cache configuration settings. Most details of the cache configuration are accessed by the CacheConfiguration and CacheContents properties of this object. The CacheConfiguration property returns an object of type FPCCacheConfiguration, and the CacheContents property returns an object of type FPCCacheContents.

FPCCache is a property of the FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCCache interface.

Methods

The following table lists the methods of the FPCCache object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCCache object.

Property | Description
CacheConfiguration | Gets an object that provides access to the cache configuration.
CacheContents | Gets an object for manipulating the contents of the cache.
ScheduledContentDownload | Gets a scheduled content download collection.
VendorParametersSets | The VendorParametersSets property Gets a reference to an object for storing and loading custom data into the FPCCache object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCache.CacheConfiguration Property

Gets an object that provides access to the cache configuration. This object is of type FPCCacheConfiguration.

VBScript Syntax[VBScript]

[ oFPCCacheConfiguration = ] FPCCache.CacheConfiguration

C++ Syntax[C++]

HRESULT get_CacheConfiguration(
  IFPCCacheConfiguration **poFPCCacheConfiguration
);

Parameters

oFPCCacheConfiguration
Reference to an FPCCacheConfiguration object.

This property is read-only.

Applies To

FPCCache


FPCCache.CacheContents Property

Gets an object for reading the contents of the cache. This is done with a reference to an FPCCacheContents object, from which you can use the FetchURL method. This method allows you to force a prefetch of sites.

VBScript Syntax[VBScript]

[ oFPCCacheContents = ] FPCCache.CacheContents

C++ Syntax[C++]

HRESULT get_CacheContents(
  IFPCCacheContents **poFPCCacheContents
);

Parameters

oFPCCacheContents
Reference to an FPCCacheContents object.

This property is read-only.

Applies To

FPCCache


FPCCache.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCCache.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCCache


FPCCache.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCCache.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCCache


FPCCache.ScheduledContentDownload Property

Gets a scheduled content download collection.

VBScript Syntax[VBScript]

[ collFPCScheduledContentDownload = ] FPCCache.ScheduledContentDownload

C++ Syntax[C++]

HRESULT get_ScheduledContentDownload(
  IFPCScheduledContentDownload **pcollFPCScheduledContentDownload
);

Parameters

collFPCScheduledContentDownload
Reference to an FPCScheduledContentDownload collection.

This property is read-only.

Applies To

FPCCache


FPCCache.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCCache object storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCCache.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCCache


FPCCacheConfiguration Object

The FPCCacheConfiguration object provides access to many ISA cache configuration settings because it is a container for the FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration objects, which provide access to active, HTTP, and FTP object-caching configuration settings, respectively.

Note To disable the cache you have to set the FPCCacheDrive.CacheLimitInMegs property = 0 for all drives. If there is cache space allocated on a drive, then the cache is automatically enabled.

The FPCCacheConfiguration object is a property of the FPCCache object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCCacheConfiguration interface.

Methods

The following table lists the methods of the FPCCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
ResetToDefaults | Discards any changes made to the cache configuration and reverts to the default cache configuration.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCCacheConfiguration object.

Property | Description
CacheQuestionUrls | Gets or sets whether caching of URLs that include the question mark is enabled or disabled.
FPCActiveCacheConfiguration | Gets a reference to an object for accessing the active cache configuration.
FTPConfiguration | Gets a reference to an object for accessing the FTP cache configuration.
HTTPConfiguration | Gets a reference to an object for accessing the HTTP cache configuration.
MemoryCacheMaxURLSize | Gets or sets the maximum size of a URL to be cached to physical memory.
MemoryUsagePercentage | Gets or sets the percentage of physical memory used for the ISA cache.
ObjectSizeLimit | Gets or sets the maximum size of a cached object.
ReturnExpiredEnable | Gets or sets whether the Web proxy returns expired cached objects when an updated object cannot be retrieved, or whether to issue an error response.
ReturnExpiredMaxTime | Gets or sets the maximum threshold (in minutes) after which the cached object would not be returned even if it expired before its ReturnExpiredEnable property threshold passed.
ReturnExpiredTTLPercent | Gets or sets the time factor to which the policy set by the ReturnExpiredEnable property applies.
SizeLimitEnable | Gets or sets whether the size limit specified by the ObjectSizeLimit property is enabled or disabled.
VendorParametersSets | Gets a reference to an object for storing and loading custom data in the FPCCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheConfiguration.CacheQuestionUrls Property

Gets or sets whether caching of URLs that include a question mark is enabled or disabled.

Note When CacheQuestionUrls is enabled, a URL that includes a question mark is cached only if the response headers indicate, using public or expires, that it is cacheable.

VBScript Syntax[VBScript]

FPCCacheConfiguration.CacheQuestionUrls [ = bEnabled ]

C++Syntax

HRESULT get_CacheQuestionUrls(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_CacheQuestionUrls(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether caching of URLs that include a question mark is enabled.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.FPCActiveCacheConfiguration Property

Gets a reference to an object for accessing the active cache configuration.

VBScript Syntax[VBScript]

[ oFPCActiveCacheConfiguration = ] FPCCacheConfiguration.FPCActiveCacheConfiguration

C++ Syntax[C++]

HRESULT get_ActiveCacheConfiguration (
  IFPCActiveCacheConfiguration **poFPCActiveCacheConfiguration
);

Parameters

oFPCActiveCacheConfiguration
Reference to the FPCActiveCacheConfiguration object.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.FTPConfiguration Property

Gets a reference to the FPCFTPCacheConfiguration object, for accessing the FTP cache configuration.

VBScript Syntax[VBScript]

[ oFPCFTPCacheConfiguration = ] FPCCacheConfiguration.FTPConfiguration

C++ Syntax[C++]

HRESULT get_FTPConfiguration (
  IFPCFTPCacheConfiguration **poFPCFTPCacheConfiguration
);

Parameters

oFPCFTPCacheConfiguration
Reference to the FPCFTPCacheConfiguration object.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.HTTPConfiguration Property

Gets a reference to the FPCHTTPCacheConfiguration object, for accessing the HTTP cache configuration.

VBScript Syntax[VBScript]

[ oFPCHTTPCacheConfiguration = ] FPCCacheConfiguration.HTTPConfiguration

C++ Syntax[C++]

HRESULT get_HTTPConfiguration (
  IFPCHTTPCacheConfiguration **poFPCHTTPCacheConfiguration
);

Parameters

oFPCHTTPCacheConfiguration
Reference to the FPCHTTPCacheConfiguration object.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.MemoryCacheMaxURLSize Property

Gets or sets the maximum URL size to be cached to physical memory. By default, objects smaller than 12,800 bytes are stored in RAM and on the disk, and all larger objects are cached only to the disk.

VBScript Syntax[VBScript]

FPCCacheConfiguration.MemoryCacheMaxURLSize [ = lMaxURLSize ]

C++ Syntax[C++]

HRESULT get_MemoryCacheMaxURLSize(
  long *plMaxURLSize
);

HRESULT put_MemoryCacheMaxURLSize(
  long lMaxURLSize
);

Parameters

lMaxURLSize
Long value that specifies the maximum size of the URL object to be cached to physical memory.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.MemoryUsagePercentage Property

Gets or sets the percentage of physical memory used for the ISA cache. If you are using a particular computer primarily for ISA, this number should be higher because it will increase the efficiency of the cache. If the computer's resources are needed for other services, you may want to consider lowering the percentage of memory used for ISA.

For more information, see ISA Server Caching Mechanism.

VBScript Syntax[VBScript]

FPCCacheConfiguration.MemoryUsagePercentage [ = lMemoryUsage ]

C++ Syntax[C++]

HRESULT get_MemoryUsagePercentage(
  long *plMemoryUsage
);

HRESULT put_MemoryUsagePercentage(
  long lMemoryUsage
);

Parameters

lMemoryUsage
Long value, in bytes, that specifies the percentage of memory used.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ObjectSizeLimit Property

Gets or sets the maximum size of an object that can be cached.

VBScript Syntax[VBScript]

FPCCacheConfiguration.ObjectSizeLimit [ = lMaxsize ]

C++ Syntax[C++]

HRESULT get_ObjectSizeLimit(
  long *plMaxsize
);

HRESULT put_ObjectSizeLimit(
  long lMaxsize
);

Parameters

lMaxsize
Long value that specifies the maximum size, in bytes, of a cached object.

The property is read-write.

See Also

FPCCacheConfiguration.SizeLimitEnable property

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCCacheConfiguration.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ResetToDefaults Method

Discards any changes made to the cache configuration and reverts to the default cache configuration.

VBScript Syntax[VBScript]

FPCCacheConfiguration.ResetToDefaults()

C++ Syntax[C++]

HRESULT ResetToDefaults();

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ReturnExpiredEnable Property

Gets or sets whether the Web proxy returns expired cached objects when an updated object cannot be retrieved, or whether to issue an error response.

VBScript Syntax[VBScript]

FPCCacheConfiguration.ReturnExpiredEnable [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_ReturnExpiredEnable(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_ReturnExpiredEnable(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the Web proxy returns expired cache objects (TRUE) or issues an error response (FALSE).

The property is read-write.

Applies To

FPCCacheConfiguration

See Also

ReturnExpiredTTLPercent


FPCCacheConfiguration.ReturnExpiredMaxTime Property

Gets or sets the maximum time during which the expired cached object would be returned. ReturnExpiredMaxTime is for situations where a server cannot be reached to revalidate an expired cached object.

VBScript Syntax[VBScript]

FPCCacheConfiguration.ReturnExpiredMaxTime [ = lFactor ]

C++ Syntax[C++]

HRESULT get_ReturnExpiredMaxTime(
  long *plFactor
);

HRESULT put_ReturnExpiredMaxTime(
  long lFactor
);

Parameters

lFactor
Long value that specifies the maximum threshold. The maximum threshold is expressed in minutes.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.ReturnExpiredTTLPercent Property

Gets or sets the time factor to which the policy set by the ReturnExpiredEnable property applies.

VBScript Syntax[VBScript]

FPCCacheConfiguration.ReturnExpiredTTLPercent [ = lFactor ]

C++ Syntax[C++]

HRESULT get_ReturnExpiredTTLPercent(
  long *plFactor
);

HRESULT put_ReturnExpiredTTLPercent(
  long lFactor
);

Parameters

lFactor
Long value that specifies the time factor. The time factor is expressed as a percentage of the object's original Time to Live (TTL).

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCCacheConfiguration.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.SizeLimitEnable Property

Gets or sets whether the size limit specified by the ObjectSizeLimit property is enabled or disabled.

VBScript Syntax[VBScript]

FPCCacheConfiguration.SizeLimitEnable [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_SizeLimitEnable(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_SizeLimitEnable(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the size limit is enabled.

The property is read-write.

Applies To

FPCCacheConfiguration


FPCCacheConfiguration.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCCacheConfiguration object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCCacheConfiguration.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCCacheConfiguration


FPCCacheContents Object

The FPCCacheContents object is used to specify to the cache the URLs that ISA will prefetch. This is achieved by using the FetchUrl method. The FetchURL method can also be used to delete an object.

For more information about using FetchUrl, see Using FetchURL to Extend the Cache.

The ISA Server cache prefetching feature lets you download content directly to the ISA Server cache, upon request or as scheduled. Prefetching allows you to update the ISA Server cache with content that you anticipate will be requested by clients in your organization.

You can configure the content that ISA Server should prefetch. You can also schedule when the content should be cached, available for access directly from the ISA Server cache, rather than from the Internet.

The FPCCacheContents object is a property of the FPCCache object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCCacheContents interface.

Methods

The following table lists the methods of the FPCCacheContents object.

Method | Description
FetchUrl | Causes the Web proxy service to retrieve an object and store it in the cache.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheContents.FetchUrl Method

Causes the Web proxy to retrieve an object and store it in the cache.

The Web proxy normally fetches objects from the Internet and caches them automatically as clients request them (passive caching). In addition, the Web proxy will automatically keep certain popular objects "fresh" within its cache by fetching them itself (active caching). However, there are occasions when an application needs a mechanism to override these automatic operations. The override lets the application exercise greater control either over the source of objects that are placed into the cache or the time they are to remain there. The FetchURL method allows you this greater degree of control.

To delete an object from the cache, set lpszFetchUrl = <empty string>, and lpszCacheUrl = <cachedURL>. When you delete an object by using FetchUrl, you can perform the operation synchronously or asynchronously, and the Time to Live (TTL) must be set to 0.

VBScript Syntax[VBScript]

FPCCacheContents.FetchUrl( lpszFetchUrl, lpszCacheUrl, lTtlInMinutes, lFlags )

C++ Syntax[C++]

HRESULT FetchUrl(
  BSTR lpszFetchUrl,
  BSTR lpszCacheUrl,
  long lTtlInMinutes,
  FpcFetchURLFlags lFlags
);

Note to C++ Programmers

The method returns an HRESULT to indicate success or failure. If the result is an error, the error code portion of the HRESULT (the low 16 bits of the value) may be a value defined by Microsoft® Win32®, WinInet (Microsoft Win32 Internet functions), or Windows Sockets (Winsock).

Parameters

lpszFetchUrl
String that specifies the URL of the object to be fetched. The URL may be any combination of protocol, domain, and path that the Web proxy would normally be able to access. The Web proxy currently supports the HTTP, FTP, and gopher protocols. If lpszFetchUrl is an empty string then the FetchUrl method removes the value in lpszCacheUrl from the cache.
lpszCacheUrl
String that specifies the URL that clients use to retrieve the fetched object from the Web proxy's cache. The URL must include one of the protocols supported by the Web proxy (http:// or ftp://), but the domain specified need not be accessible from the ISA server computer. This is because the data itself will have been read from the URL specified in the lpszFetchUrl parameter. The lpszCacheUrl parameter can be the same as the lpszFetchUrl parameter.
lTtlInMinutes
Long value that specifies the TTL, in minutes, that the object should be served from the Web proxy cache. After the TTL has passed, the object has "expired" and the Web proxy will not return it again to requesting clients unless the Web proxy first verifies that the object has not changed. In general, the application that calls FetchUrl needs to set a TTL large enough to ensure that the object will not expire before the application next refreshes it. Note that ISA can delete both fresh and expired objects from the cache if the cache directories become full.

This parameter is ignored unless the lFlags parameter includes either the fpcFetchTtlIfNone or fpcFetchTtlOverride flag. If neither flag is specified, the Web proxy's normal TTL computation mechanism is used for the object.

lFlags
Long value that specifies a set of bit flags to control the TTL of the object in the Web proxy's cache:
fpcFetchTtlOverride
Use the lTtlInMinutes flag to set the TTL for the object regardless of any "Expires" or "Cache-Control: max-age" HTTP header that the publishing Web server may have included with the object. Be careful when overriding a TTL for objects that another party authored; overriding may cause objects to be cached longer than their intended lifetimes.
fpcFetchTtlIfNone
The lTtlInMinutes flag is used to set the TTL for the object unless the publishing Web server has supplied an "Expires" or "Cache-Control: max-age" HTTP header.

If you have set neither of these flags, the Web proxy uses its normal TTL computation mechanism for the object, which uses an "Expires" or "Cache-Control: max-age" HTTP header if available. Otherwise, the Web proxy estimates a good TTL value based on the time that has elapsed since the object was last modified.

In addition to the preceding flags, you can set one or more of the following flags:

fpcFetchSynchronous
This function does not return to the caller until the fetch has completed and you have stored the object in the cache, or until an error occurs in the processing of the request. Such an error ends the operation. If you do not specify this flag, the function returns immediately and the fetch completes asynchronously to the caller, in which case it is not possible to determine whether the fetch completed successfully.
fpcFetchNoArrayRouting
If the ISA server is a member of an array, store this object in the cache of this particular proxy even if the normal array cache-sharing mechanism, the Cache Array Routing Protocol (CARP), indicates that the object should be cached on a different array member. If you do not specify this flag, the object is automatically cached on the array member that the CARP algorithm designates. This flag is ignored if the ISA server is not a member of an array. This flag therefore applies only to an array in ISA Server Enterprise Edition. It does not apply to a stand-alone server, or to ISA Server Standard Edition.
fpcFetchForceCache
Cache the object even if the caching rules in the HTTP specification normally prohibit this object from being cached; for example, if the object contains a "Cache-Control: no-cache" HTTP header or the response indicates a server error. Be careful when using this flag for objects that were authored by another party. There is often a good reason why the data could not be cached and caching it might cause the site to function improperly or might even be a violation of your license agreement for use of the data. If the sCacheUrl parameter contains a question mark, this flag alone will not allow the object to be cached. Use the FPCCacheConfiguration.CacheQuestionUrls property to enable caching URLs containing question marks.

Remarks

To retrieve a Hypertext Transfer Protocol (HTTP) object in response to a FetchUrl call, the Web proxy service uses the normal HTTP GET method to the URL specified by lpszFetchUrl. If there is already a cached copy (which was either loaded into the proxy previously by normal operations or by an earlier call to FetchUrl) of the URL specified by lpszCacheUrl, the proxy will include an "If-Modified-Since" HTTP header in the request (also known as a conditional GET). The response to a conditional GET may be either a new copy of the data, which will be stored in the cache, or an HTTP status code 304 "Not Modified" response, which will cause the proxy to extend the TTL of the object without changing the contents of the data in the cache.

To delete an object from the cache, set lpszFetchUrl =<empty string>, and lpszCacheUrl = <cachedURL>. When you delete an object using FetchUrl, you can perform the operation synchronously or asynchronously, and the TTL must be set to 0.

The DeleteURL VBScript provided with ISA in the folder SDK\samples\admin\scripts, demonstrates how to delete a cached object.

Note ERROR_INTERNET_UNABLE_TO_CACHE_FILE (decimal value 12158, hex value 2f7e) is a new value that is not present in all versions of WinInet include files. This error code is returned if the HTTP headers in the object or other factors prohibited the proxy from caching the object. The caller may still be able to force the object into the cache using the fpcFetchForceCache flag.

Applies To

FPCCacheContents


FPCCacheContents.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCCacheContents.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCCacheContents


FPCCacheDrive Object

The FPCCacheDrive object represents a single cache drive of an ISA Server computer.

This object is a member of FPCCacheDrives collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCCacheDrive interface.

Properties

The following table lists the properties of the FPCCacheDrive object.

Property | Description
CacheLimitInMegs | Gets or sets the disk size allocated to the cache.
Name | Gets the name of the drive.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheDrive.CacheLimitInMegs Property

Gets or sets the disk size allocated to the cache.

Note To disable the cache you have to set the FPCCacheDrive.CacheLimitInMegs property = 0 for all drives. If there is cache space allocated on a drive, then the cache is automatically enabled.

VBScript Syntax[VBScript]

FPCCacheDrive.CacheLimitInMegs [ = lLimit ]

C++ Syntax[C++]

HRESULT get_CacheLimitInMegs(
  long *plLimit
);

HRESULT put_CacheLimitInMegs(
  long lLimit
);

Parameters

lLimit
Long value that specifies the disk size allocated to the cache, in megabytes.

The property is read-write.

Note When you change the cache allocation, and have saved changes by using the FPCCacheDrives.Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service use the FPCArray.SendRestartNotification method.

Applies To

FPCCacheDrive


FPCCacheDrive.Name Property

Gets the name of the drive; for example, "C:" or "D:".

VBScript Syntax[VBScript]

[ sName = ] FPCCacheDrive.Name

C++Syntax

HRESULT get_Name(
  BSTR *psName
);

Parameters

sName
String that specifies the name of the drive.

The property is read-only.

Applies To

FPCCacheDrive


FPCCacheDrives Collection

The FPCCacheDrives collection provides access to a group of FPCCacheDrive objects. This collection is a property of the FPCServer object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCCacheDrives interface.

Methods

The following table lists the methods of the FPCCacheDrives collection.

Method | Description
Add | Creates a new FPCCacheDrive object in the collection and returns a reference to it.
Item | Retrieves the given FPCCacheDrive object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes one FPCCacheDrive object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCCacheDrives collection.

Property | Description
Count | Gets the number of cache drive objects in the collection.
TotalCacheInMegs | Gets the total size allocated to the cache in all drives.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCCacheDrives collections storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCacheDrives.Add Method

Creates a new FPCCacheDrive object in the collection and returns a reference to it. The Save method must be called for the additional FPCCacheDrive object to be saved to persistent storage.

An ISA Server cache drive must be in NTFS format, and have a minimum size of 5 megabytes.

VBScript Syntax[VBScript]

[ oFPCCacheDrive = ] FPCCacheDrives.Add( sName, lCacheLimitInMegs )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  long lCacheLimitInMegs,
  IFPCCacheDrive **ppoFPCCacheDrive
);

Parameters

sName
Required. String that specifies the name of the new cache drive, such as "C:".
lCacheLimitInMegs
Required. Long value that specifies the size, in megabytes, allocated to the cache in this particular drive.

Return Values

oFPCCacheDrive
Reference to the FPCCacheDrive object.

Note When you add a drive to the FPCCacheDrives collection, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service use the FPCArray.SendRestartNotification method.

Applies To

FPCCacheDrives


FPCCacheDrives.Count Property

Gets the number of FPCCacheDrive objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCCacheDrives.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of cache drive objects.

The property is read-only.

Applies To

FPCCacheDrives


FPCCacheDrives.Item Method

Retrieves the given FPCCacheDrive object from the collection specified by the method's index parameter.

VBScript Syntax[VBScript]

[ vItem = ] FPCCacheDrives.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCCacheDrive **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCCacheDrive; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCCacheDrives


FPCCacheDrives.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCCacheDrives.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCCacheDrives


FPCCacheDrives.Remove Method

Removes one FPCCacheDrive object from the collection.

VBScript Syntax[VBScript]

FPCCacheDrives.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the FPCCacheDrive object to remove.

Note When you remove a cache drive from the FPCCacheDrives collections, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service use the FPCArray.SendRestartNotification method.

Applies To

FPCCacheDrives


FPCCacheDrives.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCCacheDrives.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCCacheDrives


FPCCacheDrives.TotalCacheInMegs Property

Gets the total size allocated to the cache in all drives.

VBScript Syntax[VBScript]

[ lSize = ] FPCCacheDrives.TotalCacheInMegs

C++ Syntax[C++]

HRESULT get_TotalCacheInMegs(
  long *plSize
);

Parameters

lSize
Long value that specifies the total size, in megabytes, allocated to the cache in all drives.

The property is read-only.

Applies To

FPCCacheDrives

See Also

FPCCacheDrive


FPCCacheDrives.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCCacheDrives collection's storage. The VendorParametersSets property allows third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCCacheDrives.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCCacheDrives


FPCClientAddressSet Object

The FPCClientAddressSet object is a collection of FPCIpRange objects. Each FPCIpRange object defines a range of Internet protocols (IPs) with a lower and upper bound. As a collection of individual IP ranges, the FPCClientAddressSet object defines a set of IPs that is the union of all the ranges specified by each FPCIpRange object in the collection. FPCClientAddressSet objects are used as policy elements by ISA rules.

In ISA Management, you will see the FPCClientAddressSet object listed as the policy element Client Address Sets.

FPCClientAddressSet is a member of an FPCClientAddressSets collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCClientAddressSet interface.

Methods

The following table lists the methods of the FPCClientAddressSet object.

Method | Description
Add | Creates a new client object, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCIpRange object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an IP address from the collection.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCClientAddressSet object.

Property | Description
Count | Gets the number of FPCIpRange objects in the collection.
Description | Gets or sets the description of the client set.
Name | Gets or sets the name of the client set.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCClientAddressSet object storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientAddressSet.Add Method

Creates a new client object, inserts it into the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCIpRange = ] FPCClientAddressSet.Add( sIp_From, sIp_To )

C++ Syntax[C++]

HRESULT Add(
  BSTR sIp_From,
  BSTR sIp_To,
  IFPCIpRange **ppoFPCIpRange
);

Parameters

sIp_From
Required. String that specifies the lower bound of the IP range in x.y.z.t format.
sIp_To
Required. String that specifies the upper bound of the IP range, in x.y.z.t format.

Return Values

oFPCIpRange
Reference to the FPCIpRange object.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Count Property

Gets the number of FPCIpRange objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCClientAddressSet.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCIpRange objects.

The property is read-only.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Description Property

Gets or sets the description of the client set.

VBScript Syntax[VBScript]

FPCClientAddressSet.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the client set.

The property is read-write.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Item Method

Retrieves the given object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCClientAddressSet.Item( vIP_FromOrIndex, vMask, )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIP_FromOrIndex,
  VARIANT vMask,
  IFPCIpRange **pvItem
);

Parameters

vIP_FromOrIndex
Required. One-based index, or lower-bound or single IP of the object to retrieve.
vMask
Optional. Higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vIP_FromOrIndex.

Return Values

vItem
If successful, returns a reference to an object of type FPCIPRange; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Name Property

Gets or sets the name of the client set.

VBScript Syntax[VBScript]

FPCClientAddressSet.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the client set name.

The property is read-write.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCClientAddressSet.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCClientAddressSet


FPCClientAddressSet.Remove Method

Removes an FPCIpRange object from the collection.

VBScript Syntax[VBScript]

FPCClientAddressSet.Remove( vIpOrIndex, vIp_To )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIpOrIndex,
  VARIANT vIp_To
);

Parameters

vIpOrIndex
Required. One-based index, or lower-bound or single IP of the FPCIpRange object to remove.
vIp_To
Optional. Higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vIpOrIndex.

Applies To

FPCClientAddressSet


FPCClientAddressSet.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCClientAddressSet.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCClientAddressSet


FPCClientAddressSet.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCClientAddressSet object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCClientAddressSet.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCClientAddressSet


FPCClientAddressSets Collection

The FPCClientAddressSets collection provides access to a group of FPCClientAddressSet objects. Each object within this collection defines a set of client IPs used by a rule. Each client IP within the set is stored in an FPCIpRange object.

The FPCClientAddressSets collection is a property of an FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCClientAddressSets interface.

Methods

The following table lists the methods of the FPCClientAddressSets collection.

Method | Description
Add | Creates a new client set, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCClientAddressSet object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a client set from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCClientAddressSets collection.

Property | Description
Count | Gets the number of FPCClientAddressSet objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCClientAddressSets collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientAddressSets.Add Method

Creates a new client set, inserts it into the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCClientAddressSet = ] FPCClientAddressSets.Add( sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  IFPCClientAddressSet **ppoFPCClientAddressSet
);

Parameters

sName
Required. String that specifies the name of the new set.

Return Values

oFPCClientAddressSet
Returns a reference to the new FPCClientAddressSet object.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Count Property

Gets the number of FPCClientAddressSet objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCClientAddressSets.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCClientAddressSet objects.

The property is read-only.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Item Method

Retrieves the given FPCClientAddressSet object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCClientAddressSets.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCClientAddressSet **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCClientAddressSet; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCClientAddressSets.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCClientAddressSets


FPCClientAddressSets.Remove Method

Removes a client set from the collection.

VBScript Syntax[VBScript]

FPCClientAddressSets.Remove( vIndex, bVerify )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
  VARIANT_BOOL bVerify
);

Parameters

vIndex
Required. Name or one-based index of the FPCClientAddressSet object to remove.
bVerify
Optional. Boolean value that specifies whether COM verifies, prior to removal, if the client address set is used by a rule. The default value is TRUE.

Applies To

FPCClientAddressSets


FPCClientAddressSets.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCClientAddressSets.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCClientAddressSets


FPCClientAddressSets.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCClientAddressSets collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCClientAddressSets.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCClientAddressSets


FPCClientAutoScript Object

The FPCClientAutoScript object represents the properties of the automatic script used by browsers to work efficiently with multiple servers in an array.

You can set an option for the opening of a Web browser by a client, so that ISA automatically downloads a client configuration script located on the ISA Server computer. This script is downloaded to the browser on a client computer and is executed against every URL that the browser requests. This takes away some of the routing work that members of an ISA server array usually perform. The output of this script provides an ordered series of ISA servers that the browser uses to retrieve the object specified by the URL. The script is stored at a specific URL on any ISA server in an array. You can easily update all Web browser settings without having to reconfigure each individual Web browser.

Alternatively, you can construct your own configuration script and place it on your Web server. When a Web browser looks for the configuration script, your Web server intercepts the request and returns the custom script to the browser.

The FPCClientAutoScript object is a property of the FPCWebBrowserClientConfig object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCClientAutoScript interface.

Methods

The following table lists the methods of the FPCClientAutoScript object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCClientAutoScript object.

Property | Description
BackupRoute | Gets the client backup route.
BypassLocalServers | Gets or sets whether a client will bypass the Web proxy for requests that do not include a dot.
DirectAddressDestinations | Gets a reference to the FPCDirectAddressDestinations collection.
DirectIpDestinations | Gets a reference to the FPCDirectIpDestinations collection.
IncludeLDT | Gets or sets whether to include the Local Domain Table (LDT) addresses in the list of direct-access servers.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientAutoScript.BackupRoute Property

Gets the client backup route.

VBScript Syntax[VBScript]

[ oFPCClientBackupRoute = ] FPCClientAutoScript.BackupRoute

C++ Syntax[C++]

HRESULT get_BackupRoute (
  IFPCClientBackupRoute **poFPCClientBackupRoute
);

Return Value

oFPCClientBackupRoute
Returns a reference to an FPCClientBackupRoute object.

This property is read-only.

Applies To

FPCClientAutoScript


FPCClientAutoScript.BypassLocalServers Property

Gets or sets whether a client will bypass the Web proxy for requests that do not include a dot.

VBScript Syntax[VBScript]

FPCClientAutoScript.BypassLocalServers ( = bBypass )

C++ Syntax[C++]

HRESULT get_BypassLocalServers(
  VARIANT_BOOL *pbBypass
);

HRESULT put_BypassLocalServers(
  VARIANT_BOOL bBypass
);

Parameters

bBypass
Boolean value that specifies whether a client will bypass the Web proxy for requests that do not include a dot.

This property is read-write.

Applies To

FPCClientAutoScript


FPCClientAutoScript.DirectAddressDestinations Property

Gets a reference to the FPCDirectAddressDestinations collection.

VBScript Syntax[VBScript]

[ collFPCDirectAddressDestinations = ] FPCClientAutoScript.DirectAddressDestinations

C++ Syntax[C++]

HRESULT get_DirectAddressDestinations(
  IFPCDirectAddressDestinations **pcollFPCDirectAddressDestinations
);

Return Value

collFPCDirectAddressDestinations
Reference to the FPCDirectAddressDestinations collection.

This property is read-only.

Applies To

FPCClientAutoScript


FPCClientAutoScript.DirectIpDestinations Property

Gets a reference to the FPCDirectIpDestinations collection.

VBScript Syntax[VBScript]

[ collFPCDirectIpDestinations = ] FPCClientAutoScript.DirectIpDestinations

C++ Syntax[C++]

HRESULT get_DirectIPDestinations(
  IFPCDirectIPDestinations **pcollFPCDirectIpDestinations
);

Return Value

collFPCDirectIpDestinations
Reference to the FPCDirectIpDestinations collection.

This property is read-only.

Applies To

FPCClientAutoScript


FPCClientAutoScript.IncludeLDT Property

Gets or sets whether to include the Local Domain Table (LDT) addresses in the list of direct-access servers.

VBScript Syntax[VBScript]

FPCClientAutoScript.IncludeLDT ( = bInclude )

C++ Syntax[C++]

HRESULT get_IncludeLDT(
  VARIANT_BOOL *pbInclude
);

HRESULT put_IncludeLDT(
  VARIANT_BOOL bInclude
);

Parameters

bInclude
Boolean value that specifies whether Local Domain Table (LDT) addresses are included in the list of direct-access servers.

This property is read-write.

Applies To

FPCClientAutoScript


FPCClientAutoScript.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCClientAutoScript.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCClientAutoScript


FPCClientAutoScript.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCClientAutoScript.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCClientAutoScript


FPCClientBackupRoute Object

The FPCClientBackupRoute object represents the backup route information in the Web browser client configuration of the ISA array.You can define a backup route for Web browser clients, so that if the ISA server is available, the client will have either direct Web access, or access through an alternate server. This object is a property of the FPCClientAutoScript object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCClientBackupRoute interface.

Methods

The following table lists the methods of the FPCClientBackupRoute object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCClientBackupRoute object.

Property | Description
AutoConfigBackupRoute | Gets or sets the backup route.
ClientBackupRouteType | Gets or sets the type of the backup route. It can be either direct to the Internet or by proxy.
Enabled | Gets or sets whether the option of backup route in the Web proxy client is enabled or disabled.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientBackupRoute.AutoConfigBackupRoute Property

Gets or sets the backup route.

VBScript Syntax[VBScript]

FPCClientBackupRoute.AutoConfigBackupRoute [ = sType ]

C++ Syntax[C++]

HRESULT get_AutoConfigBackupRoute(
  BSTR *psType
);

HRESULT put_AutoConfigBackupRoute(
  BSTR sType
);

Parameters

sType
String that specifies the backup route. "DIRECT" means that the backup route is directly to the Internet rather than through an alternate proxy server.

The property is read-write.

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.ClientBackupRouteType Property

Gets or sets the type of the backup route. It can be either direct to the Internet or by proxy.

VBScript Syntax[VBScript]

FPCClientBackupRoute.ClientBackupRouteType [ = FpcBackupRouteType ]

C++ Syntax[C++]

HRESULT get_ClientBackupRouteType(
  FpcClientBackupRouteType *pFpcBackupRouteType
);

HRESULT put_ClientBackupRouteType(
  FpcClientBackupRouteType FpcBackupRouteType
);

Parameters

FpcBackupRouteType
The backup route type can have a value from the FpcClientBackupRouteType enumerated type.

The property is read-write.

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.Enabled Property

Gets or sets whether the option of backup route in the Web proxy client is enabled or disabled.

VBScript Syntax[VBScript]

FPCClientBackupRoute.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the option of backup route in the Web proxy client is enabled.

The property is read-write.

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCClientBackupRoute.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCClientBackupRoute


FPCClientBackupRoute.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCClientBackupRoute.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCClientBackupRoute


FPCClientConfig Object

The FPCClientConfig object represents the configuration that the firewall client setup application sets for the firewall client and for the client-machine web browsers. It also contains information that firewall clients download periodically from the ISA array, and information that is used for creating the browser configuration script.

This object is a property of the FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCClientConfig interface.

Methods

The following table lists the methods of the FPCClientConfig object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCClientConfig object.

Property | Description
Browser | Gets a reference to an object that allows access to the configuration of the Web proxy client browser configuration.
Firewall | Gets a reference to an object that allows access to the configuration of the Firewall client.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientConfig.Browser Property

Gets a reference to an object that allows access to the configuration of the Web proxy client browser configuration.

VBScript Syntax[VBScript]

[ oBrowserClientConfig = ] FPCClientConfig.Browser

C++ Syntax[C++]

HRESULT get_Browser(
  IFPCWebBrowserClientConfig **poBrowserClientConfig
);

Return Value

oBrowserClientConfig
Variant. Returns an object if successful; NULL otherwise.

Applies To

FPCClientConfig

See Also

FPCWebBrowserClientConfig


FPCClientConfig.Firewall Property

Gets a reference to an object that allows access to the configuration of the Firewall client.

VBScript Syntax[VBScript]

[ oFirewallClientConfig = ] FPCClientConfig.Firewall

C++ Syntax[C++]

HRESULT get_Firewall(
  IFPCFirewallClientConfig **poFirewallClientConfig
);

Return Value

oFirewallClientConfig
Variant. Returns an object if successful; NULL otherwise.

Applies To

FPCClientConfig

See Also

FPCFirewallClientConfig


FPCClientConfig.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCClientConfig.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCClientConfig


FPCClientConfig.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCClientConfig.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCClientConfig


FPCClientConfigSettings Collection

The FPCClientConfigSettings collection provides access to a group of FPCClientSettingsSection objects. Each FPCClientSettingsSection object contains sections of client settings.

The FPCClientConfigSettings collection is a property of the FPCFirewallClientConfig object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCClientConfigSettings interface.

Methods

The following table lists the methods of the FPCClientConfigSettings collection.

Method | Description
AddSection | Adds a client settings section to the collection.
Item | Returns the given FPCClientSettingsSection object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a client settings section from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCClientConfigSettings collection.

Property | Description
Count | Gets the number of FPCClientSettingsSection objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientConfigSettings.AddSection Method

Creates a new client settings section, inserts it into the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCClientSettingsSection = ] FPCClientConfigSettings.AddSection( sName )

C++ Syntax[C++]

HRESULT AddSection (
  BSTR sName,
  IFPCClientSettingsSection **ppoFPCClientSettingsSection
);

Parameters

sName
Required. String that specifies the name of the new section.

Return Values

oFPCClientSettingsSection
Returns a reference to the new FPCClientSettingsSection object.

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Count Property

Gets the number of FPCClientSettingsSection objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCClientConfigSettings.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *lCount
);

Parameters

lCount
Long value that specifies the number of FPCClientSettingsSection objects.

The property is read-only.

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Item Method

Returns the given FPCClientSettingsSection object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCClientConfigSettings.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCClientSettingsSection **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCClientSettingsSection; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.


FPCClientConfigSettings.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCClientConfigSettings.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Remove Method

Removes a client settings section from the collection.

VBScript Syntax[VBScript]

FPCClientConfigSettings.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove (
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the FPCClientSettingsSection object to remove.

Applies To

FPCClientConfigSettings


FPCClientConfigSettings.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCClientConfigSettings.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCClientConfigSettings


FPCClientSettingsSection Object

The FPCClientSettingsSection object contains sections of client settings.

These sections, together with the Local Domain Table (LDT) and the client-configuration options, comprise the information stored in mspclnt.ini, the global client configuration file. By storing the sections in the FPCClientSettingsSection object, the client configuration information will be shared and synchronized between ISA Server arrays.

For more information on mspclnt.ini, see the ISA Server product documentation.

FPCClientSettingsSection is a member of an FPCClientConfigSettings collection. Use the FPCClientConfigSettings.AddSection method to add a new FPCClientSettingsSection object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCClientSettingsSection interface.

Methods

The following table lists the methods of the FPCClientSettingsSection object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
RemoveValue | Removes a client settings value from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCClientSettingsSection object.

Property | Description
AllNames | Gets all the names of the client settings.
Name | Gets or sets the name of the client settings section object.
Value | Gets or sets the value associated with the given name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCClientSettingsSection.AllNames Property

Gets all the names of the client settings section.

VBScript Syntax[VBScript]

[ pItem = ]FPCClientSettingsSection.AllNames

C++ Syntax[C++]

HRESULT get_AllNames(
  VARIANT *pItem
);

Parameters

pItem
Pointer to a variant that returns a safe array of strings.

The property is read-only.

Remarks

The AllNames property returns a safe array of all the names of client settings stored through the Value property.

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.Name Property

Gets or sets the name of the client settings section object.

VBScript Syntax[VBScript]

FPCClientSettingsSection.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the client settings section name.

The property is read-write.

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCClientSettingsSection.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.RemoveValue Method

Removes a client setting value from the list of client settings.

VBScript Syntax[VBScript]

FPCClientSettingsSection.RemoveValue(sName)

C++ Syntax[C++]

HRESULT RemoveValue(
  BSTR sName
);

Parameters

sName
Required. String that specifies the name of the value to be removed.

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCClientSettingsSection.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCClientSettingsSection


FPCClientSettingsSection.Value Property

Gets or sets the value associated with the given name.

VBScript Syntax[VBScript]

FPCClientSettingsSection.Value (sName)[ = sValue ]

C++ Syntax[C++]

HRESULT get_Value(
  BSTR psName,
  VARIANT *psValue
);

HRESULT put_Value(
  BSTR sName,
  VARIANT sValue
);

Parameters

sName
Specifies the parameter name for which to get or set the value. The name can be of almost any type and is not necessarily a string.
sValue
The value associated with the parameter specified by the sName parameter.

The property is read-write.

Remarks

The FPCClientSettingsSection object is used to store data that is defined as {name, value} pairs using the Value property. The following example stores a property named x having a value of 1:

FPCClientSettingsSection.Value("x") = 1

The phrase Value("x") will return the value.

Applies To

FPCClientSettingsSection


FPCContentGroup Object

The FPCContentGroup object describes and provides access to the content-type groups that FPCSiteAndContentRule and FPCBandwidthRule objects can reference. The default content-type groups include Audio, Executable, Images, Text, and Video. Each group includes file types. For example, the Audio content group could include the file types .aif, .aifc, .au, .m3u, .mid, and others. If you want to change the file types that are included in a group, do so through this object by using the Add and Remove methods. You can also create additional content groups using the FPCContentGroups.Add method.

The FPCContentGroup object is a member of the FPCContentGroups collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCContentGroup interface.

Methods

The following table lists the methods of the FPCContentGroup object.

Method | Description
Add | Adds a new file type or MIME content type to the object and returns a reference to it.
Item | Retrieves the given content type from the object.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a content type from the object.
RemoveAll | Clears the list.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCContentGroup object.

Property | Description
Count | Gets the number of content types in the collection.
Description | Gets or sets the description of the group.
Name | Gets or sets the name of the group.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCContentGroup object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCContentGroup.Add Method

Adds a new file type to the object and returns a reference to it.

VBScript Syntax[VBScript]

FPCContentGroup.Add( sNewType )

C++ Syntax[C++]

HRESULT Add(
  BSTR sNewType
);

Parameters

sNewType
Required. String that specifies the name of the new MIME content type.

Applies To

FPCContentGroup


FPCContentGroup.Count Property

Gets the number of content types in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCContentGroup.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of content types.

The property is read-only.

Applies To

FPCContentGroup


FPCContentGroup.Description Property

Gets or sets the description of the group.

VBScript Syntax[VBScript]

FPCContentGroup.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the group description.

The property is read-write.

Applies To

FPCContentGroup


FPCContentGroup.Item Method

Retrieves the given content type from the object.

VBScript Syntax[VBScript]

[ vItem = ] FPCContentGroup.Item( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  VARIANT *pvItem
);

Parameters

lIndex
Required. Long value that contains the one-based index of the type to retrieve.

Return Value

vItem
If successful, returns the given content type from the object; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCContentGroup


FPCContentGroup.Name Property

Gets or sets the name of the group.

VBScript Syntax[VBScript]

FPCContentGroup.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the group name.

The property is read-write.

Applies To

FPCContentGroup


FPCContentGroup.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCContentGroup.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCContentGroup


FPCContentGroup.Remove Method

Removes a file type from the object.

VBScript Syntax[VBScript]

FPCContentGroup.Remove( sType )

C++ Syntax[C++]

HRESULT Remove(
  BSTR sType
);

Parameters

sType
Required. String that specifies the name of the MIME content type to remove.

Applies To

FPCContentGroup


FPCContentGroup.RemoveAll Method

Removes all of the content types from the object.

VBScript Syntax[VBScript]

FPCContentGroup.RemoveAll( )

C++ Syntax[C++]

HRESULT RemoveAll();

Applies To

FPCContentGroup


FPCContentGroup.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCContentGroup.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCContentGroup


FPCContentGroup.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCContentGroup object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCContentGroup.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

This property is read-only.

Applies To

FPCContentGroup


FPCContentGroups Collection

The FPCContentGroups collection provides access to a group of content collections, each represented by an individual FPCContentGroup object. This object is a property of the FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCContentGroups interface.

Methods

The following table lists the methods of the FPCContentGroups collection.

Method | Description
Add | Creates a new FPCContentGroup object.
Item | Retrieves the given FPCContentGroup object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCContentGroup object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCContentGroups collection.

Property | Description
Count | Gets the number of content group objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCDestinationSets collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCContentGroups.Add Method

Creates a new FPCContentGroup object in the collection and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCContentGroup = ] FPCContentGroups.Add( sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  IFPCContentGroup **ppoFPCContentGroup
);

Parameters

sName
Required. String that specifies the name of the new destination set.

Return Value

oFPCContentGroup
Reference to an FPCContentGroup object.

Applies To

FPCContentGroups

See Also

FPCContentGroup


FPCContentGroups.Count Property

Gets the number of content group objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCContentGroups.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of destination set objects.

The property is read-only.

Applies To

FPCContentGroups

See Also

FPCContentGroup


FPCContentGroups.Item Method

Retrieves a given FPCContentGroup object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCContentGroups.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCContentGroup **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCContentGroup; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCContentGroups


FPCContentGroups.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCContentGroups.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCContentGroups


FPCContentGroups.Remove Method

Removes a content group object from the collection.

VBScript Syntax[VBScript]

FPCContentGroups.Remove( vItem, bVerify )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vItem
  VARIANT_BOOL bVerify
);

Parameters

vItem
Required. One-based index of the object to remove.
bVerify
Optional. Boolean value that specifies whether COM verifies, prior to removal, if the content group is used by a rule. The default value is TRUE.

Applies To

FPCContentGroups

See Also

FPCContentGroup


FPCContentGroups.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCContentGroups.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCContentGroups


FPCContentGroups.VendorParametersSets Property

Gets a reference to an object for storing and loading of custom data into the FPCContentGroups collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCContentGroups.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCContentGroups


FPCCredentials Object

The FPCCredentials object lets you set the user name and password to be used when an ISA Server computer communicates with an upstream proxy server or dials out using a dial up entry. For example, chaining with another proxy server computer can require that the user name and password have been checked before chaining takes place. A routing rule that routes requests to an upstream proxy server can also check the user name and password before routing the request.

The FPCCredentials object is a property of the FPCPrimaryRoute, FPCBackupRoute, FPCDialupEntry, and FPCFirewallChaining objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCCredentials interface.

Methods

The following table lists the methods of the FPCCredentials object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCCredentials object.

Property | Description
Password | Sets the password.
UserName | Gets or sets the user name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCCredentials.Password Property

Sets the password.

VBScript Syntax[VBScript]

FPCCredentials.Password [ = sPassword ]

C++ Syntax[C++]

HRESULT put_Password(
  BSTR sPassword
);

Parameters

sPassword
String that specifies the password.

The property is write-only.

Applies To

FPCCredentials


FPCCredentials.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCCredentials.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCCredentials


FPCCredentials.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCCredentials.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCCredentials


FPCCredentials.UserName Property

Gets or sets the user name.

VBScript Syntax[VBScript]

FPCCredentials.UserName [ = sUserName ]

C++ Syntax[C++]

HRESULT get_UserName(
  BSTR *psUserName
);

HRESULT put_UserName(
  BSTR sUserName
);

Parameters

sUserName
String that specifies the user name.

The property is read-write.

Applies To

FPCCredentials


FPCDeniedMethod Object

The FPCDeniedMethod object represents a single Web-request method denied by an administrator.

There are protocols other than HTTP that make use of ports designated for HTTP use, by using methods similar to HTTP methods. You can block the use of a specific protocol by denying connections for requests containing a method specific to that protocol by using the FPCDeniedMethod object.

Note By default, all of the HTTP and HTTP-like methods are permitted unless specifically denied by the administrator.

An FPCDeniedMethod object is a member of an FPCDeniedObjects collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCDeniedMethod interface.

Methods

The following table lists the methods of the FPCDeniedMethod object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDeniedMethod object.

Property | Description
HTTPMethod | Gets or sets whether a particular method is denied.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDeniedMethod.HTTPMethod Property

Gets or sets whether a particular method is denied.

Note Add a new denied method by using FPCDeniedMethods.Add. Use the HTTPMethod property to get or to modify an existing denied method.

VBScript Syntax[VBScript]

FPCDeniedMethod.HTTPMethod( = sMethodToDeny)

C++ Syntax[C++]

HRESULT get_HTTPMethod(
  BSTR *psMethodToDeny
);

HRESULT put_HTTPMethod(
  BSTR sMethodToDeny
);

Parameters

sMethodToDeny
String that specifies the HTTP-like method to be denied.

The property is read-write.

Applies To

FPCDeniedMethod


FPCDeniedMethod.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDeniedMethod.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDeniedMethod


FPCDeniedMethod.Save Method

Saves the object's configuration to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved unless the Save method is called.

VBScript Syntax[VBScript]

FPCDeniedMethod.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDeniedMethod


FPCDeniedMethods Collection

The FPCDeniedMethods collection represents a collection of HTTP or HTTP-like methods denied by an administrator.

There are protocols other than HTTP that make use of ports designated for HTTP use by using HTTP-like methods. The FPCDeniedMethods collection of FPCDeniedMethod objects allows an administrator to block the use of specific protocols by denying connections for specific methods.

Note By default, all of the HTTP and HTTP-like methods are permitted unless specifically denied by the administrator.

The FPCDeniedMethods collection is a member of an FPCWebProxy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCDeniedMethods interface.

Methods

The following table lists the methods of the FPCDeniedMethods collection.

Method | Description
Add | Creates a new FPCDeniedMethod object, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCDeniedMethod object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCDeniedMethod object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDeniedMethods collection.

Property | Description
Count | Gets the number of FPCDeniedMethod objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDeniedMethods.Add Method

Creates a new FPCDeniedMethod object, inserts it into the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCDeniedMethod = ] FPCDeniedMethods.Add( sDeniedMethod )

C++ Syntax[C++]

HRESULT Add(
  BSTR sDeniedMethod,
  IFPCDeniedMethod **ppoFPCDeniedMethod
);

Parameters

sDeniedMethod
Required. String that specifies the method to be denied.

Return Values

oFPCDeniedMethod
Returns a reference to the FPCDeniedMethod object.

Example

The following excerpt of code adds the method PENCIL to the collection of denied methods.

Set objFPC = CreateObject("FPC.Root")
Set DeniedMethods = objFPC.Arrays.GetContainingArray.ArrayPolicy.WebProxy.DeniedMethods
DeniedMethods.Add ("PENCIL")
DeniedMethods.Save

Applies To

FPCDeniedMethods


FPCDeniedMethods.Count Property

Gets the number of FPCDeniedMethod objects in the collection.

VBScript Syntax[VBScript]

[ lCount= ] FPCDeniedMethods.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCDeniedMethod objects.

The property is read-only.

Applies To

FPCDeniedMethods


FPCDeniedMethods.Item Method

Gets the given FPCDeniedMethod object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCDeniedMethods.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCDeniedMethod **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, gets a reference to an object of type FPCDeniedMethod; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCDeniedMethods


FPCDeniedMethods.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDeniedMethods.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDeniedMethods


FPCDeniedMethods.Remove Method

Removes an FPCDeniedMethod object from the collection.

VBScript Syntax[VBScript]

FPCDeniedMethods.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the FPCDeniedMethod object to remove.

Applies To

FPCDeniedMethods


FPCDeniedMethods.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDeniedMethods.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDeniedMethods


FPCDestination Object

The FPCDestination object represents a destination that the Web proxy can access. Destinations are grouped in an FPCDestinationSet collection, which you can use to define site and content rules, publishing rules, or routing rules. For example, you can create a destination set that contains sport sites, and define a rule that prohibits access to these destinations during work hours.

A destination consists of two parts — a host description and a path within this host. For example, in "www.microsoft.com/scripting", "www.microsoft.com" is the host and "scripting" is the path. A host can be specified by domain name, IP address, or an IP range denoted by a From and To pair of settings.

An FPCDestination object is a member of an FPCDestinationSet collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCDestination interface.

Methods

The following table lists the methods of the FPCDestination object.

Method | Description
SetDestinationAsDomain | Sets the host definition by stating a host name.
SetDestinationAsIpRange | Sets the host definition by stating a range of IP addresses.
SetDestinationAsSingleIP | Sets the host definition by stating its IP address.

Properties

The following table lists the properties of the FPCDestination object.

Property | Description
DomainName | Gets the destination host name; for example, "www.microsoft.com".
Ip_From | Gets the lower-bound IP address.
Ip_To | Gets the upper-bound IP address.
Path | Gets or sets the host's path.
Type | Gets the destination type.
VendorParametersSets | Not implemented for this object..

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDestination.DomainName Property

Gets the destination host name; for example, "www.microsoft.com".

VBScript Syntax[VBScript]

[ sName = ] FPCDestination.DomainName

C++ Syntax[C++]

HRESULT get_DomainName(
  BSTR *psName
);

Parameters

sName
String that specifies the destination host name.

The property is read-only. It can be set by calling the SetDestinationAsDomain method.

Remarks

Use the following format when you specify a destination. The destination, path, and file name are not case sensitive.

Specify computer name, by using the fully qualified domain name (FQDN). For example, write destination.microsoft.com, and not //destination. The destination may begin with an asterisk (*).

To include a specific folder in the destination set: /Path/Folder_Name

To include all the files in a folder: /Path/Folder_Name/*

To select a specific file in a folder: /Path/Folder_Name/Filename

Applies To

FPCDestination


FPCDestination.Ip_From Property

Gets the lower-bound IP address.

VBScript Syntax[VBScript]

[ sIp_From = ] FPCDestination.Ip_From

C++ Syntax[C++]

HRESULT get_IP_From(
  BSTR *psIp_From
);

Parameters

sIp_From
String that specifies the lower-bound IP address.

The property is read-only.

Remarks

This property is valid only if the host definition was set by the SetDestinationAsSingleIP or SetDestinationAsIpRange method.

Applies To

FPCDestination


FPCDestination.Ip_To Property

Gets the upper-bound IP address.

VBScript Syntax[VBScript]

[ sIp_To = ] FPCDestination.Ip_To

C++ Syntax[C++]

HRESULT get_IP_To(
  BSTR *psIp_To
);

Parameters

sIp_To
String that specifies the upper-bound IP address.

The property is read-only.

Remarks

This property is valid only if the host definition was set by the SetDestinationAsIpRange method.

Applies To

FPCDestination


FPCDestination.Path Property

Sets the host's path. A path must start with a forward slash mark(/). For example: /Images/*

VBScript Syntax[VBScript]

[ sPath = ] FPCDestination.Path

C++ Syntax[C++]

HRESULT put_Path(
  BSTR *psPath
);

Parameters

sPath
String that specifies the path.

The property is read-only. It can be set by calls to the SetDestinationAsIpRange, SetDestinationAsSingleIP, or SetDestinationAsDomain methods.

Applies To

FPCDestination


FPCDestination.SetDestinationAsDomain Method

Sets the host definition by stating a host name.

VBScript Syntax[VBScript]

FPCDestination.SetDestinationAsDomain( sDomain, sPath )

C++ Syntax[C++]

HRESULT SetDestinationAsDomain(
  BSTR sDomain,
  BSTR sPath
);

Parameters

sDomain
Required. String that specifies the domain to be used.
sPath
Optional. String that specifies the path to be used.

Applies To

FPCDestination


FPCDestination.SetDestinationAsIpRange Method

Sets the host definition by stating a range of IP addresses.

VBScript Syntax[VBScript]

FPCDestination.SetDestinationAsIpRange( sIp_FromStr, sIp_ToStr, sPath )

C++ Syntax[C++]

HRESULT SetDestinationAsIpRange(
  BSTR sIp_FromStr,
  BSTR sIp_ToStr,
  BSTR sPath
);

Parameters

sIp_FromStr
Required. String that specifies the lower-bound IP address in x.y.z.t format.
sIp_ToStr
Required. String that specifies the upper-bound IP address in x.y.z.t format.
sPath
Optional. String that specifies the path property of the object.

Applies To

FPCDestination


FPCDestination.SetDestinationAsSingleIP Method

Sets the host definition by stating its IP address.

VBScript Syntax[VBScript]

FPCDestination.SetDestinationAsSingleIP( sIpStr, sPath, )

C++ Syntax[C++]

HRESULT SetDestinationAsSingleIP(
  BSTR sIpStr,
  BSTR sPath
);

Parameters

sIpStr
Required. String that specifies the IP address in x.y.z.t format.
sPath
Optional. String that specifies the path property of the object.

Applies To

FPCDestination


FPCDestination.Type Property

Gets the destination type. The type can be a domain, a single IP address, or a range of IP addresses.

VBScript Syntax[VBScript]

[ DestType = ] FPCDestination.Type

C++ Syntax[C++]

HRESULT get_Type(
  FpcDestinationAddressType *pDestType
);

Parameters

DestType
A value from the FpcDestinationAddressType enumerated type.

The property is read-only.

Applies To

FPCDestination


FPCDestinationSet Collection

The FPCDestinationSet collection defines a set of destinations stored as FPCDestination objects. The rules of an ISA server use these destinations.

You use an FPCDestinationSet collection to define site and content rules, publishing rules, and routing rules. For example, you could create a destination set containing sport sites, and then define a rule that prohibited access to these destinations during work hours.

A destination consists of two parts — a host description and a path within this host. For example, in "www.microsoft.com/scripting", "www.microsoft.com" is the host and "scripting" is the path. A host can be specified by domain name, IP address, or an IP range denoted by a From and To pair of settings.

This collection is a member of the FPCDestinationSets collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDestinationSet interface.

Methods

The following table lists the methods of the FPCDestinationSet collection.

Method | Description
Add | Creates a new FPCDestination object in the collection and returns a reference to it.
Item | Retrieves the given FPCDestination object from the collection.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a destination object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDestinationSet collection.

Property | Description
Count | Gets the number of destination objects in the collection.
Description | Gets or sets the description of the set.
Name | Gets or sets the name of the destination set.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCDestinationSet collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDestinationSet.Add Method

Creates a new FPCDestination object in the collection and returns a reference to it. The Save method must be called for the new FPCDestinationSet collection to be saved in persistent storage.

VBScript Syntax[VBScript]

[ oFPCDestination = ] FPCDestinationSet.Add( sDomainOrIpFrom, sIp_To, sPath )

C++ Syntax[C++]

HRESULT Add(
  BSTR sDomainOrIpFrom,
  BSTR sIp_To,
  BSTR sPath,
  IFPCDestination **ppoFPCDestination
);

Parameters

sDomainOrIpFrom
Required. String that specifies the domain name or IP address for the new destination.
sIp_To
Optional. String that specifies an IP upper bound that defines the destination as an IP range pair using this value and the value of the IP parameter. This parameter should be supplied only if the previous parameter is an IP address.
sPath
Optional. String value that specifies the path property of the destination to be added. A path must start with a slash mark (/). For example:/Images/*.

Return Values

oFPCDestination
Reference to the FPCDestination object.

Applies To

FPCDestinationSet


FPCDestinationSet.Count Property

Gets the number of FPCDestination objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCDestinationSet.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of destination objects.

The property is read-only.

Applies To

FPCDestinationSet


FPCDestinationSet.Description Property

Gets or sets the description of the set.

VBScript Syntax[VBScript]

FPCDestinationSet.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description.

The property is read-write.

Applies To

FPCDestinationSet


FPCDestinationSet.Item Method

Gets the given FPCDestination object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCDestinationSet.Item( vDom, sIp_To, sPath )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vDom,
  BSTR sIp_To,
  BSTR sPath,
  IFPCDestination **pvItem
);

Parameters

vDom
Required. The domain name or lower-bound IP address of the object.
sIp_To
Optional. String that specifies the higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vDom.
sPath
Optional. String value that specifies the path of the destination. A path must start with a slash mark (/). For example, /Images/*

Return Value

vItem
If successful, returns a reference to an object of type FPCDestination; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCDestinationSet


FPCDestinationSet.Name Property

Gets or sets the name of the destination set.

VBScript Syntax[VBScript]

FPCDestinationSet.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name.

The property is read-write.

Applies To

FPCDestinationSet


FPCDestinationSet.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDestinationSet.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDestinationSet


FPCDestinationSet.Remove Method

Removes a destination object from the collection.

VBScript Syntax[VBScript]

FPCDestinationSet.Remove( vDomainOrIpFrom, sIp_To, sPath )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vDomainOrIpFrom,
  BSTR sIp_To,
  BSTR sPath
);

Parameters

vDomainOrIpFrom
Required. String that specifies the domain name or IP address for the destination to be removed.
sIp_To
Optional. String that specifies the higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in vIndex.
sPath
Optional. String that specifies the path property of the object to be removed.

Applies To

FPCDestinationSet

See Also

FPCDestination


FPCDestinationSet.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDestinationSet.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDestinationSet


FPCDestinationSet.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCDestinationSet collection's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCDestinationSet.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDestinationSet


FPCDestinationSets Collection

The FPCDestinationSets collection provides access to a group of destination sets stored as FPCDestinationSet collections. You use these destination sets to define site and content rules, publishing rules, and routing rules.

Destination sets are defined in policy elements on the enteprise and array level.

This object is a property of an FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDestinationSets interface.

Methods

The following table lists the methods of the FPCDestinationSets collection.

Method | Description
Add | Creates a new FPCDestinationSet collection.
Item | Retrieves the given FPCDestinationSet collection from the collection.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a destination set object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDestinationSets collection.

Property | Description
Count | Gets the number of destination set objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCDestinationSets collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDestinationSets.Add Method

Creates a new FPCDestinationSet collection in the FPCDestinationSets collection and returns a reference to it. The Save method must be called for the new FPCDestinationSet collection to be saved to persistent storage.

VBScript Syntax[VBScript]

[ collFPCDestinationSet = ] FPCDestinationSets.Add( sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  IFPCDestinationSet **ppcollFPCDestinationSet
);

Parameters

sName
Required. String that specifies the name of the new destination set.

Return Value

collFPCDestinationSet
Reference to the new FPCDestinationSet collection.

Applies To

FPCDestinationSets


FPCDestinationSets.Count Property

Gets the number of destination set objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCDestinationSets.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of destination set objects.

The property is read-only.

Applies To

FPCDestinationSets

See Also

FPCDestinationSet


FPCDestinationSets.Item Method

Retrieves the given FPCDestinationSet collection from the FPCDestinationSets collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCDestinationSets.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCDestinationSet **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDestinationSet; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCDestinationSets


FPCDestinationSets.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDestinationSets.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDestinationSets


FPCDestinationSets.Remove Method

Removes a destination set object from the collection.

VBScript Syntax[VBScript]

FPCDestinationSets.Remove( vItem, bVerify )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vItem
  VARIANT_BOOL bVerify
);

Parameters

vItem
Required. One-based index of the object to remove.
bVerify
Optional. Boolean value that specifies whether COM verifies, prior to removal, if the destination set is used by a rule. The default value is TRUE.

Applies To

FPCDestinationSets

See Also

FPCDestinationSet


FPCDestinationSets.Save Method

Saves all the FPCDestinationSet objects in the collection to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDestinationSets.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDestinationSets


FPCDestinationSets.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCDestinationSets collection's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCDestinationSets.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDestinationSets


FPCDialupEntry Object

The FPCDialupEntry object represents a dialup entry that you can use to develop routing rules.

Note Credentials must be supplied for this object, or the Save method will fail. For more information, see the Credentials property .

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCDialupEntry interface.

Methods

The following table lists the methods of the FPCDialupEntry object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDialupEntry object.

Property | Description
Credentials | Gets an FPCCredentials object to read and write credential information.
Description | Gets or sets the description of the dialup entry.
DialupBandwidth | Gets or sets the bandwidth for a dialup entry.
DialupNetworkConnection | Gets or sets a dialup network connection.
EnableBandwidthControl | Gets or sets whether bandwidth control is enabled for the dialup entry.
Name | Gets or sets the name of the dialup entry.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCDialupEntry object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDialupEntry.Credentials Property

Gets an FPCCredentials object. This property is mandatory for an FPCDialupEntry object because the dialup entry cannot be used without credentials (user name and password that would be used to manually establish a network dial-up connection).

VBScript Syntax[VBScript]

[ oFPCCredentials = ] FPCDialupEntry.Credentials

C++ Syntax[C++]

HRESULT get_Credentials(
  IFPCCredentials **poFPCCredentials
);

Parameters

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCDialupEntry


FPCDialupEntry.Description Property

Gets or sets the description of the dialup entry. The description is stored as a string.

VBScript Syntax[VBScript]

FPCDialupEntry.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the dialup entry.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.DialupBandwidth Property

Gets or sets the dialup bandwidth.

Bandwidth for connections through an external network adapter are set by using the FPCBandwidthRules.TotalExternalBandwidth property.

Note For a modem, the bandwidth depends on the actual speed of the modem, compression, and other factors.

VBScript Syntax[VBScript]

FPCDialupEntry.DialupBandwidth [= lDialupBandwidth ]

C++ Syntax[C++]

HRESULT get_DialupBandwidth(
  BSTR *plDialupBandwidth
);

HRESULT set_DialupBandwidth(
  BSTR lDialupBandwidth
);

Parameters

lDialupBandwidth
Long value that specifies the bandwidth for the dialup entry.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.DialupNetworkConnection Property

Gets or sets the name of the dialup network connection.This must be defined as network dial-up connection on all of the servers in the array.

VBScript Syntax[VBScript]

FPCDialupEntry.DialupNetworkConnection [= sConnection ]

C++ Syntax[C++]

HRESULT get_DialupNetworkConnection(
  BSTR *psConnection
);

HRESULT set_DialupNetworkConnection(
  BSTR sConnection
);

Parameters

sConnection
String that specifies the name of the dialup network connection.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.EnableBandwidthControl Property

Gets or sets whether bandwidth control is enabled for the dialup entry.

Bandwidth control is an ISA Server mechanism that informs the Windows 2000 QoS packet scheduling service how to prioritize connections that pass through ISA Server.

VBScript Syntax[VBScript]

FPCDialupEntry.EnableBandwidthControl [ = bEnabled]

C++ Syntax[C++]

HRESULT get_EnableBandwidthControl(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_EnableBandwidthControl(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean that specifies whether bandwidth control is enabled.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.Name Property

Gets or sets the name of the dialup entry object.

VBScript Syntax[VBScript]

FPCDialupEntry.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the alert object.

The property is read-write.

Applies To

FPCDialupEntry


FPCDialupEntry.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDialupEntry.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDialupEntry


FPCDialupEntry.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDiDialupEntry.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDialupEntry


FPCDialupEntry.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection is backed up from the Active Directory with all other ISA objects.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCDialupEntry.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDialupEntry


FPCDialupEntries Collection

The FPCDialupEntries collection provides access to a group of FPCDialupEntry objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCDialupEntries interface.

Methods

The following table lists the methods of the FPCDialupEntries collection.

Method | Description
Add | Creates a new Dialup entry, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCDialupEntry object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an object from the collection
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDialupEntries collection.

Property | Description
ActiveEntry | Gets or sets the active dial-up entry.
Count | Gets the number of objects in the collection
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCDialupEntries collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDialupEntries.ActiveEntry Property

Gets or sets the active FPCDialupEntry object. Only one dial-up entry can be active at a time. The active dial-up entry may be used for routing rules and firewall chaining. You cannot delete the active entry.

Note When you set an active dial-up entry, all existing dial-up connections are disconnected.

VBScript Syntax[VBScript]

FPCDialupEntries.ActiveEntry [ = sDialUpEntryName ]

C++ Syntax[C++]

HRESULT get_ActiveEntry(
  BSTR *psDialUpEntryName
);

HRESULT put_ActiveEntry(
  BSTR sDialUpEntryName
);

Parameters

sDialUpEntryName
String value that specifies the name of the active dialup entry.

The property is read-write.

Applies To

FPCDialupEntries


FPCDialupEntries.Add Method

Creates a new FPCDialupEntry in the FPCDialupEntries collection and returns a reference to it. The Save method must be called for the new FPCDialupEntry to be saved to persistent storage.

VBScript Syntax[VBScript]

[ oFPCDialupEntry = ] FPCDialupEntries.Add( sName, sDialupNetworkConnection)

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  BSTR sDialupNetworkConnection,
  IFPCDialupEntry **ppoFPCDialupEntry
);

Parameters

sName
Required. String that specifies the name of the new dialup entry.
sDialupNetworkConnection
String identifying the dialup network connection to be used in the dialup entry.

Return Value

oFPCDialupEntry
Reference to the FPCDialupEntry object.

Applies To

FPCDialupEntries


FPCDialupEntries.Count Property

Gets the number of FPCDialupEntry objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCDialupEntries.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of dialup entry objects.

The property is read-only.

Applies To

FPCDialupEntries


FPCDialupEntries.Item Method

Retrieves the given FPCDialupEntry object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCDialupEntries.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCDialupEntry **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDialupEntry; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCDialupEntries


FPCDialupEntries.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDialupEntries.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDialupEntries


FPCDialupEntries.Remove Method

Removes an FPCDialupEntry object from the collection.

Note The Remove method will fail for the active dialup entry. For more information, see FPCDialupEntries.ActiveEntry.

VBScript Syntax[VBScript]

FPCDialupEntries.Remove( vItem )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vItem
);

Parameters

vItem
Required. Name or one-based index of the object to remove.

Applies To

FPCDialupEntries


FPCDialupEntries.Save Method

Saves all the FPCDialupEntry objects in the collection to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDialupEntries.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDialupEntries


FPCDialupEntries.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection is backed up from the Active Directory with all other ISA objects.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCDialupEntries.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCDialupEntries


FPCDialupNetworkConnections Collection

The FPCDialupNetworkConnections collection provides access to a group of dialup network connection names from the phone book of an ISA Server computer or ISA array. This object is a property of the FPCServer object.

Note This collection is not part of persistent storage and retrieves data from the dialup connections file of the specified server.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDialupNetworkConnections interface.

Methods

The following table lists the methods of the FPCDialupNetworkConnections collection.

Method | Description
Item | Retrieves the dialup entries in the given index from the collection.
Refresh | Reads all the dialup entries from the dialup connections file.

Properties

The following table lists the properties of the FPCDialupNetworkConnections collection.

Property | Description
Count | Gets the number of dialup connection entries in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDialupNetworkConnections.Count Property

Gets the number of dialup connection entries in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCDialupNetworkConnections.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of dialup connection entries.

The property is read-only.

Applies To

FPCDialupNetworkConnections


FPCDialupNetworkConnections.Item Method

Gets the dialup connection entries in the given index from the collection. The return value is a variant that contains the name of the entry. The return value is -1 if the entry specified by the lIndex parameter does not exist.

VBScript Syntax[VBScript]

[ vitem = ] FPCDialupNetworkConnections.Item( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  VARIANT *pvItem
);

Parameters

lIndex
Required. One-based index of the object to retrieve.

Return Value

vItem
Returns a variant that contains the name of the entry, or -1 if the entry specified by vIndex does not exist.

Applies To

FPCDialupNetworkConnections


FPCDialupNetworkConnections.Refresh Method

Reads all the phone book entries from the phone book by using an RPC call. The FPCDialupNetworkConnections collection is not part of persistent storage and retrieves data from the phone-book file of the specified server. An RPC call is used to query ISA services about its sessions because the information is dynamic.

VBScript Syntax[VBScript]

FPCDialupNetworkConnections.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDialupNetworkConnections


FPCDirectAddressDestination Object

The FPCDirectAddressDestination object represents a single direct address destination in the client configuration of the ISA array, specified by domain name. You can define addresses that the client will access directly rather than through the ISA Server.

This object is a member of the FPCDirectAddressDestinations collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDirectAddressDestination interface.

Methods

The following table lists the methods of the FPCDirectAddressDestination object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDirectAddressDestination object.

Property | Description
DomainName | Gets or sets the domain name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectAddressDestination.DomainName Property

Gets or sets the domain name.

VBScript Syntax[VBScript]

FPCDirectAddressDestination.DomainName [ = sDomain ]

C++ Syntax[C++]

HRESULT get_DomainName(
  BSTR *psDomain
);

HRESULT put_DomainName(
  BSTR sDomain
);

Parameters

sDomain
String that specifies the domain name.

The property is read-write.

Applies To

FPCDirectAddressDestination


FPCDirectAddressDestination.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDirectAddressDestination.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDirectAddressDestination


FPCDirectAddressDestination.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDirectAddressDestination.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDirectAddressDestination


FPCDirectAddressDestinations Collection

The FPCDirectAddressDestinations collection provides access to a group of FPCDirectAddressDestination objects. Clients access each destination in this collection directly; that is, they bypass the Firewall service. It is a property of the FPCClientAutoScript object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDirectAddressDestinations interface.

Methods

The following table lists the methods of the FPCDirectAddressDestinations collection.

Method | Description
AddDomainSuffix | Adds a domain suffix.
Item | Retrieves the given FPCDirectAddressDestination object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCDirectAddressDestination object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDirectAddressDestinations collection.

Property | Description
Count | Gets the number of destination objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectAddressDestinations.AddDomainSuffix Method

Adds a domain suffix and returns a reference to an FPCDirectAddressDestination object. You can indicate a group of addresses that the client can access directly, rather than through the ISA Server, by specifying a domain suffix for which direct access is allowed.

VBScript Syntax[VBScript]

[ oFPCDirectAddressDestination = ] FPCDirectAddressDestinations.AddDomainSuffix( sDomain )

C++ Syntax[C++]

HRESULT AddDomainSuffix (
  BSTR sDomain,
  IFPCDirectAddressDestination **ppoFPCDirectAddressDestination

);Parameter

sDomain
String value that specifies the domain.

Return Value

oFPCDirectAddressDestination
Returns a reference to an FPCDirectAddressDestination object.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Count Property

Gets the number of FPCDirectAddressDestination objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCDirectAddressDestinations.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of direct destination objects.

The property is read-only.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Item Method

Retrieves the given FPCDirectAddressDestination object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCDirectAddressDestinations.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCDirectAddressDestination **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDirectAddressDestination; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDirectAddressDestinations.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Remove Method

Removes an FPCDirectAddressDestination object from the collection.

VBScript Syntax[VBScript]

FPCDirectAddressDestinations.Remove( vItem )

C++ Syntax[C++]

HRESULT Remove (
  VARIANT vItem
);

Parameters

vItem
Required. Name or one-based index of the object to remove.

Applies To

FPCDirectAddressDestinations


FPCDirectAddressDestinations.Save Method

Saves all the FPCDirectAddressDestination objects in the collection to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDirectAddressDestinations.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDirectAddressDestinations


FPCDirectIpDestination Object

The FPCDirectIpDestination object represents a range of IP destinations in the client configuration of an ISA array. You can indicate an address or group of addresses that the client can access directly, rather than through the ISA Server, by specifying an IP address or range of IP addresses for which direct access is allowed. The range can consist of a single IP address, if you give FPCDirectIpDestination.IP_From the same value as FPCDirectIpDestination.IP_To.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDirectIpDestination interface.

Methods

The following table lists the methods of the FPCDirectIpDestination object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetIps | Sets the range of IP destination addresses.

Properties

The following table lists the properties of the FPCDirectIpDestination object.

Property | Description
IP_From | Gets the base IP address of the range.
IP_To | Gets the end of the IP range of the range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectIpDestination.IP_From Property

Gets the lower-bound IP address of the range.

VBScript Syntax[VBScript]

[ sIp = ] FPCDirectIpDestination.IP_From

C++ Syntax[C++]

HRESULT get_IP_From(
  BSTR *psIp
);

Parameters

sIp
String that specifies the lower-bound IP address of the range.

The property is read-write.

Applies To

FPCDirectIpDestination


FPCDirectIpDestination.IP_To Property

Gets the upper bound of the IP range.

VBScript Syntax[VBScript]

FPCDirectIpDestination.IP_To ( =sIp )

C++ Syntax[C++]

HRESULT get_IP_To(
  BSTR *psIp
);

Parameters

sIp
String that specifies the upper-bound IP address of the range.

The property is read-write.

Applies To

FPCDirectIpDestination


FPCDirectIpDestination.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDirectIpDestination.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDirectIpDestination


FPCDirectIpDestination.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDirectIpDestination.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDirectIpDestination


FPCDirectIpDestination.SetIps Method

Sets the range of IP destination addresses.

VBScript Syntax[VBScript]

FPCDirectIpDestination.SetIps( = sNewFrom, sNewTo )

C++ Syntax[C++]

HRESULT SetIps(
  BSTR sNewFrom
  BSTR sNewTo
);

Parameters

sNewFrom
String that specifies the lower-bound IP address of the range. This IP address cannot be greater that that provided in sNewTo.
sNewTo
String that specifies the upper-bound IP address of the range. It can be equal to the IP address in sNewFrom, resulting in a range consisting of a single address.

Applies To

FPCDirectIpDestination


FPCDirectIpDestinations Collection

The FPCDirectIpDestinations collection is a collection of Internet Protocol (IP) destinations for which clients will bypass the ISA Server. You can use this object to access the collection of FPCDirectIpDestination objects. It is a property of the FPCClientAutoScript object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDirectIpDestinations interface.

Methods

The following table lists the methods of the FPCDirectIpDestinations collection.

Method | Description
AddIp | Adds a range of IP addresses to the collection.
Item | Retrieves a given FPCDirectIpDestination object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCDirectIpDestination object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCDirectIpDestinations collection.

Property | Description
Count | Gets the number of destination objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDirectIpDestinations.AddIp Method

Adds a range of IP addresses to the collection, in the form of an FPCDirectIPDestination object.

VBScript Syntax[VBScript]

[ oFPCDirectIpDestination ] FPCDirectIpDestinations.AddIp( sIP_From, sIP_To )

C++ Syntax[C++]

HRESULT AddIP (
  BSTR sIP_From,
  BSTR sIP_To,
  IFPCDirectIPDestination **ppoFPCDirectIpDestination
);

Parameters

sIP_From
String that specifies the base IP address of the range.
sIP_To
String that specifies the end of the IP range.

Return Values

oFPCDirectIpDestination
Returns a reference to an FPCDirectIpDestination object.

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Count Property

Gets the number of FPCDirectIpDestination objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCDirectIpDestinations.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of IP destination objects.

The property is read-only.

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Item Method

Retrieves the given FPCDirectIpDestination object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCDirectIpDestinations.Item( vIp_FromOrIndex, vIp_To )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIp_FromOrIndex,
  VARIANT vIp_To,
  IFPCDirectIPDestination **pvItem
);

Parameters

vIp_FromOrIndex
One-based index of the object to retrieve, or domain name or lower-bound IP.
vIp_To
Optional. String that specifies the higher-bound IP of the object to retrieve; needed if providing a lower-bound IP in IP_FromOrIndex.

Return Value

vItem
If successful, returns a reference to an object of type FPCDirectIpDestination; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDirectIpDestinations.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Remove Method

Removes an FPCDirectIpDestination object from the collection.

VBScript Syntax[VBScript]

FPCDirectIpDestinations.Remove( vIpOrIndex, vIpTo )

C++ Syntax[C++]

HRESULT Remove (
  VARIANT vIpOrIndex,
  VARIANT vIpTo
);

Parameters

vIpOrIndex
Required. One-based index or lower-bound IP address of the destination(s) to remove.
vIpTo
Optional. Upper-bound IP address of the destinations to remove. Necessary if vIpOrIndex provides a lower-bound IP address.

Applies To

FPCDirectIpDestinations


FPCDirectIpDestinations.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCDirectIpDestinations.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCDirectIpDestinations


FPCDiskDrive Object

The FPCDiskDrive object represents a single disk drive of an ISA Server computer. This object lets you read the drive's properties.

This object is a member of the FPCDiskDrives collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCDiskDrive interface.

Properties

The following table lists the properties of the FPCDiskDrive object.

Property | Description
CurrentCacheInMegs | Gets the amount of disk space being used by the cache.
DiskSizeInMegs | Gets the size of the disk.
FileSystem | Gets the name of the file system.
FreeSpaceInMegs | Gets the size of the free space, in megs, on the current disk.
Name | Gets the name of the drive.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDiskDrive.CurrentCacheInMegs Property

Gets the amount of disk space being used by the cache.

VBScript Syntax[VBScript]

[ lCurrentCache = ] FPCDiskDrive.CurrentCacheInMegs

C++ Syntax[C++]

HRESULT get_CurrentCacheInMegs(
  long *plCurrentCache
);

Parameters

lCurrentCache
Long value that specifies, in megabytes, how much of the disk space is currently being used by the cache.

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrive.DiskSizeInMegs Property

Gets the size of the disk in megabytes.

VBScript Syntax[VBScript]

[ lSize = ] FPCDiskDrive.DiskSizeInMegs

C++ Syntax[C++]

HRESULT get_DiskSizeInMegs(
  long *plSize
);

Parameters

lSize
Long value that specifies the size, in megabytes, of the disk.

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrive.FileSystem Property

Gets the name of the file system.

VBScript Syntax[VBScript]

[ sName = ] FPCDiskDrive.FileSystem

C++ Syntax[C++]

HRESULT get_FileSystem(
  BSTR *psName
);

Parameters

sName
String that specifies the name of the file system. For example, "FAT", "FAT32", or "NTFS".

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrive.FreeSpaceInMegs Property

Gets the size of the free space, in megabytes, on the current disk.

VBScript Syntax[VBScript]

[ lSize = ] FPCDiskDrive.FreeSpaceInMegs

C++ Syntax[C++]

HRESULT get_FreeSpaceInMegs(
  long *plSize
);

Parameters

lSize
Long value that specifies the size, in megabytes, of the free space on the current disk.

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrive.Name Property

Gets the name of the drive; for example, "C:" or "D:". The drive name that is returned cannot be changed with this property.

VBScript Syntax[VBScript]

[ sName = ] FPCDiskDrive.Name

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

Parameters

sName
String that specifies the name of the drive.

The property is read-only.

Applies To

FPCDiskDrive


FPCDiskDrives Collection

The FPCDiskDrives collection provides access to a group of FPCDiskDrive objects. This object is a property of an FPCServer object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCDiskDrives interface.

Methods

The following table lists the methods of the FPCDiskDrives collection.

Method | Description
Item | Retrieves the given FPCDiskDrive object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.

Properties

The following table lists the properties of the FPCDiskDrives collection.

Property | Description
Count | Gets the number of disk drive objects in the collection.
TotalCurrentCacheInMegs | Gets the total amount of disk space currently being used by the cache.
TotalDiskSizeInMegs | Gets the total amount of disk space in all NTFS file system drives.
TotalFreeSizeInMegs | Gets the total amount of free space in all NTFS file system drives.
VendorParametersSets | Not implemented for this object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCDiskDrives.Count Property

Gets the number of FPCDiskDrive objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCDiskDrives.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCDiskDrive objects.

The property is read-only.

Applies To

FPCDiskDrives


FPCDiskDrives.Item Method

Retrieves the given FPCDiskDrive object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCDiskDrives.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCDiskDrive **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCDiskDrive; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCDiskDrives


FPCDiskDrives.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCDiskDrives.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCDiskDrives


FPCDiskDrives.TotalCurrentCacheInMegs Property

Gets the total amount of disk space currently being used by the cache.

VBScript Syntax[VBScript]

[ lCurrentCache = ] FPCDiskDrives.TotalCurrentCacheInMegs

C++ Syntax[C++]

HRESULT get_TotalCurrentCacheInMegs(
  long *plCurrentCache
);

Parameters

lCurrentCache
Long value that specifies the total amount of disk space currently used by the cache, in megabytes.

The property is read-only.

Applies To

FPCDiskDrives


FPCDiskDrives.TotalDiskSizeInMegs Property

Gets the total amount of disk space in all NTFS file system drives.

VBScript Syntax[VBScript]

[ lSize = ] FPCDiskDrives.TotalDiskSizeInMegs

C++ Syntax[C++]

HRESULT get_TotalDiskSizeInMegs(
  long *plSize
);

Parameters

lSize
Long value that specifies the total size, in megabytes, of free space in all NTFS file system drives.

The property is read-only.

Applies To

FPCDiskDrives

See Also

FPCDiskDrive


FPCDiskDrives.TotalFreeSizeInMegs Property

Gets the total amount of free space in all NTFS file system drives.

VBScript Syntax[VBScript]

[ lSize = ] FPCDiskDrives.TotalFreeSizeInMegs

C++ Syntax[C++]

HRESULT get_TotalFreeSizeInMegs(
  long *plSize
);

Parameters

lSize
Long value that specifies the total size, in megabytes, of free space in all NTFS file system drives.

The property is read-only.

Applies To

FPCDiskDrives

See Also

FPCDiskDrive


FPCEnterprise Object

The FPCEnterprise object provides access to the enterprise policy interfaces. The enterprise policy includes site and content rules and protocol rules. The enterprise policy can be applied to any array, and can be augmented by the array's own policy. This allows administrators at branch and departmental levels to adopt governing enterprise policies.

The FPCEnterprise object is a property of the FPC root object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCEnterprise interface.

Methods

The following table lists the methods of the FPCEnterprise object.

Method | Description
Backup | Backs up the all enterprise configuration to a file.
GetSecurityDescriptor | Gets the security descriptor.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Restore | Restores all original values to the FPCEnterprise object.
Save | Saves the object's configuration to persistent storage.
SetPolicy | Sets the values of the PolicyUsedFlag and the DefaultPolicy properties.
SetSecurityDescriptor | Sets the security descriptor.

Properties

The following table lists the properties of the FPCEnterprise object.

Property | Description
AllowPublishing | Gets or sets a Boolean value that specifies the default value for any array that is not in the FPCArrayPolicyConfigs collection.
ArrayPolicyConfigs | Gets an object holding a collection that maps each array to an enterprise policy.
BackupComment | Gets the backup comment from a file.
BackupCreatedTime | Gets the time that the backup file was created.
DefaultPolicy | Gets the name of the default enterprise policy, or NULL for using the first policy in the FPCEnterprisePolicies collection.
EnterprisePolicies | Gets an object holding all enterprise policies.
Extensions | Gets an FPCExtensions object.
ForcePacketFiltering | Gets or sets whether an administrator can disable IP packet filtering.
PolicyElements | Gets an object holding all enterprise policy configurations.
PolicyUsedFlag | Gets a value that specifies the default value for any array that is not in the FPCArrayPolicyConfigs collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCEnterprise object storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEnterprise.AllowPublishing Property

Gets or sets a Boolean value that specifies whether publishing is allowed for any array that is not in the FPCArrayPolicyConfigs collection.

VBScript Syntax[VBScript]

FPCEnterprise.AllowPublishing [ = bAllow ]

C++ Syntax[C++]

HRESULT get_AllowPublishing(
  VARIANT_BOOL *pbAllow
);

HRESULT put_AllowPublishing(
  VARIANT_BOOL bAllow
);

Return Values

bAllow
A Boolean value that specifies whether publishing is allowed in the current array.

This property is read-write.

Remarks

Publishing rules cannot be created at the enterprise level. However, the enterprise administrator can specify, by using the FPCEnterprise.AllowPublishing property, whether an array is allowed to publish servers. If the array is allowed to publish, the array administrator can create Web publishing rules (FPCWebPublishingRule object) or server publishing rules (FPCServerPublishingRule object). If the enterprise policy does not allow publishing, then an attempt to add a Web or server publishing rule will return an error message.

Applies to

FPCEnterprise


FPCEnterprise.ArrayPolicyConfigs Property

Gets a collection of all arrays and how enterprise policy is applied to them.

VBScript Syntax[VBScript]

[ collFPCArrayPolicyConfigs = ] FPCEnterprise.ArrayPolicyConfigs

C++ Syntax[C++]

HRESULT get_ArrayPolicyConfigs(
  IFPCArrayPolicyConfigs **pcollFPCArrayPolicyConfigs
);

Parameters

collFPCArrayPolicyConfigs
Reference to an FPCArrayPolicyConfigs collection.

This property is read-only.

Applies To

FPCEnterprise

See Also

FPCArrayPolicyConfig


FPCEnterprise.Backup Method

Backs up the enterprise policy configuration to a file.

VBScript Syntax[VBScript]

FPCEnterprise.Backup ( sFileName, sComment, bOverwrite )

C++ Syntax[C++]

HRESULT Backup (
  BSTR sFileName,
  BSTR sComment,
  VARIANT_BOOL bOverwrite,
);

Parameters

sFileName
A string value that specifies the name of the file that will contain a copy of the information after the operation is complete.
sComment
Optional. A string value that specifies a comment that can be added to the backup file.
bOverwrite
Optional. A Boolean value that specifies whether to allow the operation to continue when a backup file with the same name already exists.

Applies to

FPCEnterprise


FPCEnterprise.BackupComment Property

Gets the backup comment from a file.

VBScript Syntax[VBScript]

[ sBackupComment = ] FPCEnterprise.BackupComment ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupComment (
  BSTR sFileName,
  BSTR *psBackupComment
);

Parameters

sFileName
A string value that specifies the name of the file that contains a backup of the enterprise information.

Return Values

sBackupComment
A string value that specifies a comment that was added to the backup file when it was created.

The property is read-only. The backup comment is set by using the Backup method.

Applies to

FPCEnterprise


FPCEnterprise.BackupCreatedTime Property

Gets the time that the backup file was created.

VBScript Syntax[VBScript]

[ dTime = ] FPCEnterprise.BackupComment ( sFileName )

C++ Syntax[C++]

HRESULT get_BackupComment (
  BSTR sFileName,
  DATE *pdTime
);

Parameters

sFileName
A string value that specifies the name of the file that contains a backup of the enterprise information.

Return Values

dTime
A date value that specifies the time that the backup file was created.

The property is read-only.

Applies to

FPCEnterprise


FPCEnterprise.DefaultPolicy Property

Gets the name of the default enterprise policy, or NULL for the first policy in the FPCEnterprisePolicies collection. This policy is used for any array that is not in the FPCArrayPolicyConfigs collection.

VBScript Syntax[VBScript]

[ sPolicyName = ] FPCEnterprise.DefaultPolicy

C++ Syntax[C++]

HRESULT get_DefaultPolicy(
  BSTR *psPolicyName
);

Parameters

sPolicyName
String value that specifies the name of the default policy.

The property is read-only.

Applies To

FPCEnterprise


FPCEnterprise.EnterprisePolicies Property

Gets a reference to an FPCEnterprisePolicies collection.

VBScript Syntax[VBScript]

[ collFPCEnterprisePolicies = ] FPCEnterprise.EnterprisePolicies

C++ Syntax[C++]

HRESULT get_EnterprisePolicies(
  IFPCEnterprisePolicies **pcollFPCEnterprisePolicies
);

Return Value

collFPCEnterprisePolicies
Reference to the FPCEnterprisePolicies collection.

This property is read-only.

Applies To

FPCEnterprise


FPCEnterprise.Extensions Property

Gets an FPCExtensions object. In an enterprise, the FPCExtensions object is used to administer application filter protocols (FPCFilterProtocols collection)that have been registered in the enterprise. From an array (FPCArray.Extensions), the FPCExtensions object is used to administer all configuration settings of ISA extensions (including application filter protocols that have been registered on the array level). ISA extensions include application filters and Web filters.

VBScript Syntax[VBScript]

[ oFPCExtensions = ] FPCEnterprise.Extensions

C++ Syntax[C++]

HRESULT get_Extensions(
  IFPCExtensions **poFPCExtensions
);

Parameters

oFPCExtensions
Reference to an FPCExtensions object.

The property is read-only.

Applies to

FPCEnterprise


FPCEnterprise.ForcePacketFiltering Property

Gets or sets whether IP packet filtering is "forced" in an array. When IP packet filtering is forced, the administrator is prevented from disabling IP packet filtering. True (forced) is the default value for arrays in the FPCArrayPolicyConfigs collection.

Note If the enterprise administrator forces packet filtering through the FPCEnterprise.ForcePacketFiltering property, an array administrator will not be able to disable packet filtering through the FPCIpPacketFilter.Enabled property.

FPCEnterprise.ForcePacketFiltering [ = bForce ]

C++ Syntax[C++]

HRESULT get_ForcePacketFiltering(
  VARIANT_BOOL *pbForce
);

HRESULT put_ForcePacketFiltering(
  VARIANT_BOOL bForce
);

Return Values

bForce
Boolean value that specifies whether IP packet filtering is forced in an array.

The property is read-write.

Applies To

FPCEnterprise


FPCEnterprise.GetSecurityDescriptor Method

Returns an FPCSecurityDescriptor object, or a Win32 security descriptor, that represents security settings.

VBScript Syntax[VBScript]

[ vSecurityDescriptor = ] FPCEnterprise.GetSecurityDescriptor( lSecurityInfo, bBinary )

C++ Syntax[C++]

HRESULT GetSecurityDescriptor (
  LONG lSecurityInfo,
  VARIANT_BOOL bBinary,
  VARIANT *pvSecurityDescriptor
);

Parameters

lSecurityInfo
Long value that specifies security information.
bBinary
Boolean value that determines whether you get the security descriptor in binary form.

Return Value

vSecurityDescriptor
Reference to an FPCSecurityDescriptor object. If you specify that the security descriptor is in binary form, this is a reference to a Win32 security descriptor in self-relative format. For more information on Win32 security descriptors, see MSDN.

Remarks

This method uses related Windows functionality. For more information, see GetSecurityInfo in MSDN.

Applies to

FPCEnterprise


FPCEnterprise.PolicyElements Property

Gets an object holding all enterprise policy configurations. The FPCPolicyElements object itself has many properties that are important to ISA configuration, such as all scheduling information, destination sets, client address sets, protocol definitions, all filtering information, and all bandwidth class information. You can access these configuration areas programmatically.

VBScript Syntax[VBScript]

[ oFPCPolicyElements = ] FPCEnterprise.PolicyElements

C++ Syntax[C++]

HRESULT get_PolicyElements(
  IFPCPolicyElements **poFPCPolicyElements
);

Parameters

oFPCPolicyElements
Reference to an FPCPolicyElements object.

This property is read-only.

Applies To

FPCEnterprise


FPCEnterprise.PolicyUsedFlag Property

Gets a value that specifies the default policy-used value, as set by using the FPCEnterprise.SetPolicy method.

If you set the FPCArrayPolicyConfig.UseDefaults property to TRUE, the array will use the default policy configuration set in the FPCEnterprise object. If you set the FPCArrayPolicyConfig.UseDefaults property to FALSE, the array will use the policy you define by using the FPCArrayPolicyConfig.SetPolicy method.

VBScript Syntax[VBScript]

[ PolicyUsed = ] FPCEnterprise.PolicyUsedFlag

C++ Syntax[C++]

HRESULT get_PolicyUsedFlag(
  FpcPolicyUsed *pPolicyUsed
);

Parameters

PolicyUsed
Specifies the default value for allowing local policy. It can have a value from the FpcPolicyUsed enumerated type.

The property is read-only.

Applies To

FPCEnterprise


FPCEnterprise.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCEnterprise.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCEnterprise


FPCEnterprise.Restore Method

Restores the enterprise configuration from a file.

VBScript Syntax[VBScript]

FPCEnterprise.Restore ( sFileName )

C++ Syntax[C++]

HRESULT Restore(
  BSTR sFileName
);

Parameters

sFileName
A string value that specifies the name of the file that contains the enterprise configuration.

Applies to

FPCEnterprise


FPCEnterprise.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCEnterprise.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCEnterprise


FPCEnterprise.SetPolicy Method

Sets the default enterprise policy settings, by setting the values of the PolicyUsedFlag and the DefaultPolicy properties. These define whether an array uses array policy, enterprise policy, or both, and the name of the enterprise policy to be used.

The default enterprise policy is the policy used for an array when you set the FPCArrayPolicyConfig.UseDefaults property to TRUE.

VBScript Syntax[VBScript]

FPCEnterprise.SetPolicy( PolicyUsed, sDefaultPolicy )

C++ Syntax[C++]

HRESULT SetPolicy(
  FpcPolicyUsed PolicyUsed,
  BSTR sDefaultPolicy
);

Parameters

PolicyUsed
A value from the FpcPolicyUsed enumerated type that specifies whether the array uses its local and/or enterprise policy.
sDefaultPolicy
String that specifies the name of the default policy. It can be empty if the enterprise policy is not being used.

Remarks

If no array is using the default enterprise policy, any FpcPolicyUsed value can be used in the PolicyUsed parameter.

If there is an array using these default enterprise policy settings, the following rules apply to changes in the value of the PolicyUsed parameter:

  • fpcEnterprisePolicyUsed to fpcArrayAndEnterprisePoliciesUsed - allowed
  • fpcArrayAndEnterprisePoliciesUsed to fpcEnterprisePolicyUsed - allowed.
  • fpcArrayAndEnterprisePoliciesUsed or fpcEnterprisePolicyUsed to fpcArrayPolicyUsed - not allowed.
  • fpcArrayPolicyUsed to fpcArrayAndEnterprisePoliciesUsed or fpcEnterprisePolicyUsed - not allowed.

For information on setting the FpcPolicyUsed value for the policy of a specific array, including limitations on changes to this value, see FPCArrayPolicyConfig.SetPolicy.

Applies To

FPCEnterprise


FPCEnterprise.SetSecurityDescriptor Method

Sets the values of the FPCSecurityDescriptor object or Microsoft® Win32® security descriptor that represents security settings.

VBScript Syntax[VBScript]

FPCEnterprise.SetSecurityDescriptor( lSecurityInfo, vSecurityDescriptor )

C++ Syntax[C++]

HRESULT SetSecurityDescriptor (
  LONG lSecurityInfo,
  VARIANT vSecurityDescriptor
);

Parameters

lSecurityInfo
Long value specifying security information.
vSecurityDescriptor
Variant that can be either a reference to an FPCSecurityDescriptor object, or a pointer to a Win32 security descriptor in self-relative format. For more information on Win32 security descriptors, see MSDN.

Remarks

This method uses related Windows functionality. For more information, see SetSecurityInfo in MSDN.

Applies to

FPCEnterprise


FPCEnterprise.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection is backed up from the Active Directory with all other ISA objects.

VBScript Syntax[VBScript]

[ oFPCVendorParametersSets = ] FPCEnterprise.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **poFPCVendorParametersSets
);

Parameters

oFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEnterprise


FPCEnterprisePolicy Object

The FPCEnterprisePolicy object defines a single ISA policy. A policy is a combination of rules and IP packet filters that you define, and that can be applied on the array level or enterprise level. Each ISA policy contains configurable properties.

This object is a member of the FPCEnterprisePolicies collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCEnterprisePolicy interface.

Methods

The following table lists the methods of the FPCEnterprisePolicy object.

Method | Description
GetSecurityDescriptor | Gets the security descriptor.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetSecurityDescriptor | Sets the security descriptor.

Properties

The following table lists the properties of the FPCEnterprisePolicy object.

Property | Description
CreatedTime | Gets a DATE data type that specifies the creation time of the object.
Description | Gets or sets the description of the policy in the form of a string.
LastModifiedTime | Gets a DATE that specifies the last modification time of the object.
Name | Gets or sets the name of the policy.
ProtocolRules | Gets a collection of the protocol rules.
SiteAndContentRules | Gets a collection of all site and content rules.
VendorParametersSets | Gets a reference to an object used to access a vendor's data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEnterprisePolicy.CreatedTime Property

Gets the creation time of the enterprise policy object.

VBScript Syntax[VBScript]

[ dCreatedTime = ] FPCEnterprisePolicy.CreatedTime

C++ Syntax[C++]

HRESULT get_CreatedTime(
  DATE *pdCreatedTime
);

Parameters

dCreatedTime
Reference to the DATE data type that specifies the creation time of the enterprise policy object.

The property is read-only.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.Description Property

Gets or sets the description of the policy. The description is stored as a string.

VBScript Syntax[VBScript]

FPCEnterprisePolicy.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the policy.

The property is read-write.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.GetSecurityDescriptor Method

Returns an FPCSecurityDescriptor object, or a Win32 security descriptor, that represents the security settings of this policy.

VBScript Syntax[VBScript]

[ vSecurityDescriptor = ] FPCEnterprisePolicy.GetSecurityDescriptor( lSecurityInfo, bBinary )

C++ Syntax[C++]

HRESULT GetSecurityDescriptor (
  LONG lSecurityInfo,
  VARIANT_BOOL bBinary,
  VARIANT *pvSecurityDescriptor
);

Parameters

lSecurityInfo
Long value specifying security information.
bBinary
Boolean value that determines whether you get the security descriptor in binary form.

Return Value

vSecurityDescriptor
Reference to an FPCSecurityDescriptor object. If you specify that the security descriptor is in binary form, this is a reference to a Win32 security descriptor in self-relative format. For more information on Win32 security descriptors, see MSDN.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.LastModifiedTime Property

Gets the last modification time of the object.

VBScript Syntax[VBScript]

[ dLastModifiedTime = ] FPCEnterprisePolicy.LastModifiedTime

C++ Syntax[C++]

HRESULT get_LastModifiedTime(
  DATE *pdLastModifiedTime
);

Parameters

dLastModifiedTime
Reference to a DATE data type that specifies the last modification time of the object.

The property is read-only.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.Name Property

Gets or sets the name of the policy. The name of the policy is stored as a string.

VBScript Syntax[VBScript]

FPCEnterprisePolicy.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the policy name.

The property is read-write.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.ProtocolRules Property

Gets a collection of the protocol rules in this policy.

VBScript Syntax[VBScript]

[ collFPCProtocolRules = ] FPCEnterprisePolicy.ProtocolRules

C++ Syntax[C++]

HRESULT get_ProtocolRules(
  IFPCProtocolRules **pcollFPCProtocolRules
);

Parameters

collFPCProtocolRules
Reference to the FPCProtocolRules collection.

The property is read-only

Applies To

FPCEnterprisePolicy

See Also

FPCProtocolRule


FPCEnterprisePolicy.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCEnterprisePolicy.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCEnterprisePolicy.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.SetSecurityDescriptor Method

Sets the values of the FPCSecurityDescriptor object or Win32 security descriptor that represents security settings of this policy.

VBScript Syntax[VBScript]

FPCEnterprisePolicy.SetSecurityDescriptor( lSecurityInfo, vSecurityDescriptor )

C++ Syntax[C++]

HRESULT SetSecurityDescriptor(
  LONG lSecurityInfo,
  VARIANT vSecurityDescriptor
);

Parameters

lSecurityInfo
Long value that specifies security information.
vSecurityDescriptor
Variant that can be either a reference to an FPCSecurityDescriptor object, or a pointer to a Win32 security descriptor in self-relative format. For more information on Win32 security descriptors, see MSDN.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicy.SiteAndContentRules Property

Gets a collection of the site and content rules in this policy.

VBScript Syntax[VBScript]

[ collFPCSiteAndContentRules = ] FPCEnterprisePolicy.SiteAndContentRules

C++ Syntax[C++]

HRESULT get_SiteAndContentRules(
  IFPCSiteAndContentRules **pcollFPCSiteAndContentRules
);

Parameters

collFPCSiteAndContentRules
Reference to the FPCSiteAndContentRules collection.

The property is read-only

Applies To

FPCEnterprisePolicy

See Also

FPCSiteAndContentRule


FPCEnterprisePolicy.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection is backed up from the Active Directory with all other ISA objects.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCEnterprisePolicy.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEnterprisePolicy


FPCEnterprisePolicies Collection

The FPCEnterprisePolicies collection provides access to a collection of FPCEnterprisePolicy objects.

FPCEnterprisePolicies is a property of the FPCEnterprise object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCEnterprisePolicies interface.

Methods

The following table lists the methods of the FPCEnterprisePolicies collection.

Method | Description
Add | The Add method of the FPCEnterprisePolicies collection adds a new policy to the collection.
Item | Retrieves the given FPCEnterprisePolicy object from the collection.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes the policy object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCEnterprisePolicies collection.

Property | Description
Count | Gets the number of policy objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCEnterprisePolicies collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEnterprisePolicies.Add Method

Adds a new policy to the collection and returns a reference to it. Only enterprise administrators can change the enterprise policy settings and create or modify new enterprise policies. For more information, see the ISA Server product documentation.

VBScript Syntax[VBScript]

[ oFPCEnterprisePolicy = ] FPCEnterprisePolicies.Add( sName, sPolicyToClone )

C++ Syntax[C++]

HRESULT Add (
  BSTR sName,
  BSTR sPolicyToClone,
  IFPCEnterprisePolicy **ppoFPCEnterprisePolicy
);

Parameters

sName
Required. String that specifies the name of FPCEnterprisePolicy object to add.
sPolicyToClone
Optional. String that specifies the policy name to which to copy the configuration.

Return Value

oFPCEnterprisePolicy
Returns a reference to the new FPCEnterprisePolicy object.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Count Property

Gets the number of policy objects within the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCEnterprisePolicies.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCEnterprisePolicy objects.

The property is read-only.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Item Method

Retrieves the given FPCEnterprisePolicy object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCEnterprisePolicies.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCEnterprisePolicy **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCEnterprisePolicy; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCEnterprisePolicies.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Remove Method

Removes a policy from the collection.

VBScript Syntax[VBScript]

FPCEnterprisePolicies.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the FPCEnterprisePolicy object to remove.

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCEnterprisePolicies.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCEnterprisePolicies


FPCEnterprisePolicies.VendorParametersSets Property

Gets a reference to an object that stores vendor-specific data. The VendorParametersSets property allows third-party extensions to be integrated into ISA. Any third-party data that is loaded into the FPCVendorParametersSets collection is backed up from the Active Directory with all other ISA objects.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCEnterprisePolicies.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEnterprisePolicies


FPCEventDefinition Object

The FPCEventDefinition object is used to define a single event. Events describe conditions that require the attention of an administrator. Predetermined actions can be taken in response to particular events by using the FPCAlert object. Each event is uniquely identified by its EventGUID property.

This object is a member of the FPCEventDefinitions collection.

For a more detailed programmatic example of using the FPCEventDefinitions collection, see Adding a Custom Event and Alert.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCEventDefinition interface.

Methods

The following table lists the methods of the FPCEventDefinition object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCEventDefinition object.

Property | Description
AdditionalKeys | Gets the additional keys to this event.
AdditionalKeysCount | Gets the number of additional keys to this event.
Description | Gets or sets the description of the event.
EventGUID | Gets the GUID of the event.
EventsBeforeRaise | Gets or sets the default count of events that signals another event.
IsISAEvent | Gets whether the event is installed by ISA.
MinEventsPerSecond | Gets or sets the default count of events per second that signals another event.
MinutesBeforeReRaise | Gets or sets the interval between invocations of the default count of minutes that signals another event.
Name | Gets or sets the name of the event.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCEventDefinition object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEventDefinition.AdditionalKeys Property

Gets the additional keys to this event.

Additional keys serve as a way to subdivide event objects into related subevents; for example, subdividing a service-started event into ISA services subevents. This allows for different alerts that are specific to subevents or one alert that is specific to all subevents.

Note The additional key with an index = 0 means all subevents.

VBScript Syntax[VBScript]

[ vKeys = ] FPCEventDefinition.AdditionalKeys

C++ Syntax[C++]

HRESULT get_AdditionalKeys(
  VARIANT *pvKeys
);

Parameters

vKeys
Variant array that specifies the additional keys.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.AdditionalKeysCount Property

Gets the number of additional keys for this event.

VBScript Syntax[VBScript]

[ lCount = ] FPCEventDefinition.AdditionalKeysCount

C++ Syntax[C++]

HRESULT get_AdditionalKeysCount(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of additional keys.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.Description Property

Gets or sets the description of the event.

VBScript Syntax[VBScript]

FPCEventDefinition.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the event description.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.EventGUID Property

Gets the globally unique identifier (GUID) of the event.

VBScript Syntax[VBScript]

[ sGUID = ] FPCEventDefinition.EventGUID

C++ Syntax[C++]

HRESULT get_EventGUID(
  BSTR *psGUID
);

Parameters

sGUID
String that specifies the GUID of the event.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.EventsBeforeRaise Property

Gets or sets the default count of events that signals another event. This property only establishes a default value for an event. When you create an alert, the alert can use the default value, or you can overwrite it with values specific to the alert by modifying the corresponding property in the FPCAlert object.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties of the FPCAlert object set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second, and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The EventsBeforeRaise property sets the threshold for the number of times the alert has been signaled.

VBScript Syntax[VBScript]

FPCEventDefinition.EventsBeforeRaise [ = lThreshold ]

C++ Syntax[C++]

HRESULT get_EventsBeforeRaise(
  long *plThreshold
);

HRESULT put_EventsBeforeRaise(
  long lThreshold
);

Parameters

lThreshold
Long value that specifies the threshold.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.IsISAEvent Property

Gets whether the event is installed by ISA.

Note The events installed by ISA cannot be deleted.

VBScript Syntax[VBScript]

[ bISAEvent = ]FPCEventDefinition.IsISAEvent

C++ Syntax[C++]

HRESULT get_IsISAEvent(
  VARIANT_BOOL *pbISAEvent
);

Parameters

bISAEvent
A Boolean value that specifies whether an event is installed by ISA.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinition.MinEventsPerSecond Property

Gets or sets the default count of events per second that signals another event. This property only establishes a default value for an event. When you create an alert, the alert can use the default value, or you can overwrite it with values specific to the alert by modifying the corresponding property in the FPCAlert object.

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties of the FPCAlert object set the three thresholds that the alert service uses to signal alerts. For each alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second, and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinEventsPerSecond property sets the threshold for the number of alerts signaled per second.

VBScript Syntax[VBScript]

FPCEventDefinition.MinEventsPerSecond [ = lThreshold ]

C++ Syntax[C++]

HRESULT get_MinEventsPerSecond(
  long *plThreshold
);

HRESULT put_MinEventsPerSecond(
  long lThreshold
);

Parameters

lThreshold
Long value that specifies the threshold for the number of alerts signaled per second.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.MinutesBeforeReRaise Property

Gets or sets the interval between invocations of the default count of minutes that signals another event).

The MinutesBeforeReRaise, EventsBeforeRaise, and MinEventsPerSecond properties of the FPCAlert object set the three thresholds that the alert service uses to signal alerts. For each individual alert, the alert service stores the last time the alert was signaled, a count of how many times the alert has been signaled per second, and a count of the total number of times the alert has been signaled. An alert is given and the alert invokes the actions specific to the alert only when the three threshold requirements for signaling an alert are met simultaneously.

The MinutesBeforeReRaise property sets the threshold for the last time the alert was signaled.

This property only establishes a default value for an event. When you create an alert, the alert can use the default value, or you can overwrite it with values specific to the alert by modifying the corresponding property in the FPCAlert object.

VBScript Syntax[VBScript]

FPCEventDefinition.MinutesBeforeReRaise [ = lInterval ]

C++ Syntax[C++]

HRESULT get_MinutesBeforeReRaise(
  long *plInterval
);

HRESULT put_MinutesBeforeReRaise(
  long lInterval
);

Parameters

lInterval
Long value that specifies the signaling interval.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.Name Property

Gets or sets the name of the event.

VBScript Syntax[VBScript]

FPCEventDefinition.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the event name.

Note The event name must be unique.

The property is read-write.

Applies To

FPCEventDefinition


FPCEventDefinition.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCEventDefinition.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCEventDefinition


FPCEventDefinition.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCEventDefinition.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCEventDefinition


FPCEventDefinition.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCEventDefinition object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCEventDefinition.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEventDefinition


FPCEventDefinitions Collection

FPCEventDefinitions gives access to a collection of FPCEventDefinition objects. Events describe conditions that require the attention of an administrator, and predetermined actions can be taken in response to particular events by using the FPCAlert object.

For a more detailed programmatic example of using the FPCEventDefinitions collection, see Adding a Custom Event and Alert.

This collection is a property of the FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCEventDefinitions interface.

Methods

The following table lists the methods of the FPCEventDefinitions collection.

Method | Description
Add | Creates a new event, inserts it into the collection, and returns a reference to it.
Item | Retrieves the given FPCEventDefinition object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an event definition from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCEventDefinitions collection.

Property | Description
Count | Gets the number of event-definition objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCEventDefinitions collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCEventDefinitions.Add Method

Creates a new event, inserts it into the collection, and returns a reference to it. Creating a new event can only be done through the ISA administration COM objects, not in ISA Management.

VBScript Syntax[VBScript]

[ oFPCEventDefinition = ] FPCEventDefinitions.Add( sName, sEventGUID, vAdditionalKeys )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  BSTR sEventGUID,
  VARIANT *pvAdditionalKeys,
  IFPCEventDefinition **ppoFPCEventDefinition
);

Parameters

sName
Required. String that specifies the name of the new event. Name should be unique in the collection.
sEventGUID
Required. String that specifies the globally unique identifier (GUID) of the new event.
vAdditionalKeys
Optional. Reference to a string array of subevents. See FPCEventDefinition.AdditionalKeys.

Return Values

oFPCEventDefinition
Returns a reference to the FPCEventDefinition object of the new event.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Count Property

Gets the number of event definition objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCEventDefinitions.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCEventDefinition objects.

The property is read-only.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Item Method

Returns the given FPCEventDefinition object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCEventDefinitions.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCEventDefinition **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCEventDefinition; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCEventDefinitions.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCEventDefinitions


FPCEventDefinitions.Remove Method

Removes an event definition from the collection.

VBScript Syntax[VBScript]

FPCEventDefinitions.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the FPCEventDefinition object to remove.

Applies To

FPCEventDefinitions


FPCEventDefinitions.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCEventDefinitions.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCEventDefinitions


FPCEventDefinitions.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCEventDefinitions collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCEventDefinitions.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCEventDefinitions


FPCExtensions Object

The FPCExtensions object is used to administer all configuration settings of ISA extensions. ISA extensions include application filters and Web filters.

Application filters work with the Firewall service to intercept and process data. Application filters can access the data stream or datagrams associated with a session within the Firewall service. The filters are registered with the Firewall service and act in response to events detected by the service. An application filter can perform protocol-specific or system-specific tasks, such as authentication and checking for viruses.

Web filters are dynamic-link libraries (DLLs) that are loaded when the ISA Web proxy service is started, and stay in memory until the service shuts down. Once loaded, Web filters can be configured to receive a number of special filter-event notifications. These filter-event notifications occur with each HTTP request that the ISA Web proxy service receives and with each response returned through the ISA Web proxy by an external Web server.

This object is a property of the FPCArray and FPCEnterprise objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCExtensions interface.

Methods

The following table lists the methods of the FPCExtensions object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCExtensions object.

Property | Description
ApplicationFilters | Gets an FPCApplicationFilters collection.
WebFilters | Gets an FPCWebFilters collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCExtensions.ApplicationFilters Property

Gets an FPCApplicationFilters collection.

VBScript Syntax[VBScript]

[ collFPCApplicationFilters = ] FPCExtensions.ApplicationFilters

C++ Syntax[C++]

HRESULT get_ApplicationFilters(
  IFPCApplicationFilters **pcollFPCApplicationFilters
);

Parameters

collFPCApplicationFilters
Reference to an FPCApplicationFilters collection.

The property is read-only.

Applies To

FPCExtensions


FPCExtensions.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCExtensions.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCExtensions


FPCExtensions.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCExtensions.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCExtensions


FPCExtensions.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCExtensions object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCExtensions.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to an FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCExtensions


FPCExtensions.WebFilters Property

Gets an FPCWebFilters collection.

VBScript Syntax[VBScript]

[ collFPCWebFilters = ] FPCExtensions.WebFilters

C++ Syntax[C++]

HRESULT get_WebFilters(
  IFPCWebFilters **pcollFPCWebFilters
);

Parameters

collFPCWebFilters
Reference to an FPCWebFilters collection.

The property is read-only.

Applies To

FPCExtensions


FPCFilterProtocol Object

The FPCFilterProtocol object is used to represent a single protocol registered by a application filter. An application filter can register a particular protocol so that it appears in ISA Management. FPCFilterProtocol is a member of the FPCFilterProtocols collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCFilterProtocol interface.

Methods

The following table lists the methods of the FPCFilterProtocol object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCFilterProtocol object.

Property | Description
ApplicationFilterGuid | Gets the globally unique identifier (GUID) that identifies the application filter. The vendor of the application filter provides the GUID.
Description | Gets or sets the description of the application filter protocol.
Guid | Gets the GUID that identifies the protocol.
Name | Gets the name of the application filter protocol.
PrimaryConnections | Gets a collection of all of this protocol's primary connections.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCFilterProtocol object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFilterProtocol.ApplicationFilterGuid Property

Gets the GUID that identifies the application filter. The vendor of the application filter provides the GUID.

VBScript Syntax[VBScript]

[ sGuid = ] FPCFilterProtocol.ApplicationFilterGuid

C++ Syntax[C++]

HRESULT get_ApplicationFilterGuid(
  BSTR *psGuid
);

Parameters

sGuid
String that specifies the GUID.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocol.Description Property

Gets or sets the description of the application filter protocol.

VBScript Syntax[VBScript]

FPCFilterProtocol.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String specifying the description of the protocol.

The property is read-write.

Applies To

FPCFilterProtocol


FPCFilterProtocol.Guid Property

Gets the globally unique identifier (GUID) that identifies the protocol.

VBScript Syntax[VBScript]

[ sGuid = ] FPCFilterProtocol.Guid

C++ Syntax[C++]

HRESULT get_Guid(
  BSTR *psGuid
);

Parameters

sGuid
String that specifies the GUID.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocol.Name Property

Gets the name of the application filter protocol.

VBScript Syntax[VBScript]

[ sName = ] FPCFilterProtocol.Name

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

Parameters

sName
String that specifies the protocol name.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocol.PrimaryConnections Property

Gets a collection of all of this protocol's primary connections.

VBScript Syntax[VBScript]

[ collFPCProtocolConnections = ] FPCFilterProtocol.PrimaryConnections

C++ Syntax[C++]

HRESULT get_PrimaryConnections(
  IFPCProtocolConnections **pcollFPCProtocolConnections
);

Parameters

collFPCProtocolConnections
Reference to an FPCProtocolConnections collection.

The property is read-only.

Remarks

An application filter protocol must list its primary outbound connections in the FPCProtocolConnections collection. The Firewall service uses the list to determine which NAT connections should be processed by the service.

Secondary connections should not be listed here.

Applies To

FPCFilterProtocol


FPCFilterProtocol.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCFilterProtocol.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCFilterProtocol


FPCFilterProtocol.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCFilterProtocol.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCFilterProtocol


FPCFilterProtocol.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCFilterProtocol object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCFilterProtocol.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCFilterProtocol


FPCFilterProtocols Collection

Represents all protocols that a single application filter supports. This object is used to access the collection of FPCFilterProtocol objects.

FPCFilterProtocols is a property of the FPCApplicationFilter object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCFilterProtocols interface.

Methods

The following table lists the methods of the FPCFilterProtocols collection.

Method | Description
Add | Adds a new FPCFilterProtocol object to the collection.
Item | Retrieves the given Firewall service FPCFilterProtocol object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an application filter protocol object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCFilterProtocols collection.

Property | Description
Count | Gets the number of application filter protocols in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCFilterProtocol object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFilterProtocols.Add Method

Adds a new FPCFilterProtocol object to the collection.

VBScript Syntax[VBScript]

[ oFPCFilterProtocol = ] FPCFilterProtocols.Add( sGuid, sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sGuid,
  BSTR sName,
  IFPCFilterProtocol **ppoFPCFilterProtocol
);

Parameters

sGuid
Required. String that specifies the globally unique identifier (GUID) of the new application filter.
sName
Required. String that specifies the name of the protocol.

Return Value

oFPCFilterProtocol
Reference to an FPCFilterProtocol object.

Applies To

FPCFilterProtocols


FPCFilterProtocols.Count Property

Gets the number of application filter protocols in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCFilterProtocols.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value specifying the number of application filter protocols.

The property is read-only.

Applies To

FPCFilterProtocols

See Also

FPCFilterProtocol


FPCFilterProtocols.Item Method

Retrieves the given Firewall service FPCFilterProtocol object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCFilterProtocols.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCFilterProtocol **pvItem
);

Parameters

vIndex
Required. Globally unique identifier (GUID) or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCFilterProtocol; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCFilterProtocols


FPCFilterProtocols.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCFilterProtocols.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCFilterProtocols


FPCFilterProtocols.Remove Method

Removes an FPCFilterProtocol object from the collection.

VBScript Syntax[VBScript]

FPCFilterProtocols.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Globally unique identifier (GUID) or one-based index of the object to remove.

Applies To

FPCFilterProtocols


FPCFilterProtocols.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCFilterProtocols.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCFilterProtocols


FPCFilterProtocols.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCFilterProtocols collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCFilterProtocols.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCFilterProtocols


FPCFirewallClientConfig Object

The FPCFirewallClientConfig object represents the configuration of the Firewall client of an ISA array. This object is a property of the FPCClientConfig object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCFirewallClientConfig interface.

Methods

The following table lists the methods of the FPCFirewallClientConfig object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCFirewallClientConfig object.

Property | Description
AccessType | Gets or sets how to represent the connection between the Firewall client and the Firewall service.
AutoDetect | Gets or sets whether autodetect is enabled.
ServerIp | Gets or sets whether the Firewall client accesses the ISA server by using the server's IP address. This method assumes that the value of the AccessType property is fpcClientAccessSetByIp.
ServerOrArrayName | Gets or sets the name of the ISA server used by Firewall clients. This method assumes that the value of the AccessType property is fpcClientAccessSetByName.
Settings | Gets the Firewall client configuration settings.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallClientConfig.AccessType Property

Gets or sets whether to represent the connection between the Firewall client and the Firewall service by IP address or by name.

VBScript Syntax[VBScript]

FPCFirewallClientConfig.AccessType [ = AccessType ]

C++ Syntax[C++]

HRESULT get_AccessType(
  FpcFwAccessByType *pAccessType
);

HRESULT put_AccessType(
  FpcFwAccessByType AccessType
);

Parameters

AccessType
Communication level. It can have a value from the FpcFwAccessByType enumerated type.

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.AutoDetect Property

Gets or sets whether the auto detect option is enabled. Auto detect, also known as automatic discovery, allows you to configure clients so that they automatically discover the appropriate ISA Server computer. This is particularly useful for roaming clients. For more information, see the ISA product documentation.

VBScript Syntax[VBScript]

FPCFirewallClientConfig.AutoDetect [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_AutoDetect(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_AutoDetect(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the auto detect function is enabled.

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCFirewallClientConfig.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCFirewallClientConfig.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.ServerIp Property

Gets or sets the IP address of the ISA server used by Firewall clients. This method assumes that the value of the AccessType property is fpcClientAccessSetByIp.

VBScript Syntax[VBScript]

FPCFirewallClientConfig.ServerIp [ = sIP ]

C++ Syntax[C++]

HRESULT get_ServerIP(
  BSTR *psIP
);

HRESULT put_ServerIP(
  BSTR sIP
);

Parameters

sIP
String that specifies the IP address of the server.

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.ServerOrArrayName Property

Gets or sets the name of the ISA server used by Firewall clients. This method assumes that the value of the AccessType property is fpcClientAccessSetByName.

VBScript Syntax[VBScript]

FPCFirewallClientConfig.ServerOrArrayName [ = sName ]

C++ Syntax[C++]

HRESULT get_ServerOrArrayName(
  BSTR *psName
);

HRESULT put_ServerOrArrayName(
  BSTR sName
);

Parameters

sName
String that specifies the name of the server.

Applies To

FPCFirewallClientConfig


FPCFirewallClientConfig.Settings Property

Gets the Firewall client settings in an FPCClientConfigSettings collection.

VBScript Syntax[VBScript]

[ collFPCClientConfigSettings = ] FPCFirewallClientConfig.Settings

C++ Syntax[C++]

HRESULT get_Settings(
  IFPCClientConfigSettings **ppcollFPCClientConfigSettings
);

Parameters

collFPCClientConfigSettings
Reference to an FPCClientConfigSettings collection.

Applies To

FPCFirewallClientConfig


FPCFirewallChaining Object

The FPCFirewallChaining object defines Firewall service chainings. You can use Firewall service chaining to configure the routing of Firewall service requests among the servers.

You can use the FPCFirewallChaining object to determine whether chaining is enabled and to determine the name of the array or server to which to chain.

The FPCFirewallChaining object is a property of the FPCNetworkConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCFirewallChaining interface.

Methods

The following table lists the methods of the FPCFirewallChaining object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCFirewallChaining object.

Property | Description
AuthenticationEnabled | Gets or sets whether use of authentication in upstream routing is enabled.
ChainingAutoDialOut | Gets a reference to an object that represents the automatic-dial settings of the chaining connection.
Credentials | Gets an FPCCredentials object used to read and write credential information. This information is used if a firewall server needs to authenticate when it chains to an upstream firewall server.
ForwardTo | Gets the name of the server or array to which to chain.
ForwardType | Gets or sets the mode of firewall forwarding.
PrimaryAutoDialOut | Gets a reference to an object that represents the automatic-dial settings of the primary connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallChaining.AuthenticationEnabled Property

Gets or sets whether use of authentication in upstream routing is enabled.

VBScript Syntax[VBScript]

FPCFirewallChaining.AuthenticationEnabled [= bEnabled ]

C++ Syntax[C++]

HRESULT get_AuthenticationEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_AuthenticationEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether authentication is enabled.

The property is read-write.

Applies To

FPCFirewallChaining


FPCFirewallChaining.ChainingAutoDialOut Property

Gets a reference to an object that represents the automatic-dial settings of the chaining connection.

VBScript Syntax[VBScript]

[ oFPCAutoDial = ] FPCFirewallChaining.ChainingAutoDialOut

C++ Syntax[C++]

HRESULT get_ChainingAutoDialOut(
  IFPCAutoDial **poFPCAutoDial
);

Parameters

oFPCAutoDial
Reference to an FPCAutoDial object.

The property is read-only.

Applies To

FPCFirewallChaining


FPCFirewallChaining.Credentials Property

Gets an FPCCredentials object used to read and write credential information. A server will use this information if it needs to authenticate when chaining to an upstream server.

VBScript Syntax[VBScript]

[ oFPCCredentials = ] FPCFirewallChaining.Credentials

C++ Syntax[C++]

HRESULT get_Credentials(
  IFPCCredentials **poFPCCredentials
);

Parameters

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCFirewallChaining


FPCFirewallChaining.ForwardTo Property

Gets or sets the name or IP address of the server or array to which to chain.

VBScript Syntax[VBScript]

FPCFirewallChaining.ForwardTo [ = sName ]

C++ Syntax[C++]

HRESULT get_ForwardTo(
  BSTR *psName
);

HRESULT put_ForwardTo(
  BSTR sName
);

Parameters

sName
String that specifies the name or IP address of the server or array.

The property is read-write.

Applies To

FPCFirewallChaining


FPCFirewallChaining.ForwardType Property

Gets or sets the how requests are chained, either forwarding requests to the primary connection, or forwarding requests to another firewall server.

VBScript Syntax[VBScript]

FPCFirewallChaining.ForwardType [ = ForwardType ]

C++ Syntax[C++]

HRESULT get_ForwardType(
  FpcFwForwardType *pForwardType
);

HRESULT put_ForwardType(
  FpcFwForwardType ForwardType
);

Parameters

ForwardType
Type of forwarding. It can have a value from the FpcFwForwardType enumerated type.

The property is read-write.

Applies To

FPCFirewallChaining


FPCFirewallChaining.PrimaryAutoDialOut Property

Gets a reference to an object that represents the automatic-dial settings of the primary connection.

VBScript Syntax[VBScript]

[ oAutoDial = ] FPCFirewallChaining.PrimaryAutoDialOut

C++ Syntax[C++]

HRESULT get_PrimaryAutoDialOut(
  IFPCAutoDial **poAutoDial
);

Parameters

oAutoDial
Reference to an FPCAutoDial object.

The property is read-only.

Applies To

FPCFirewallChaining


FPCFirewallChaining.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCFirewallChaining.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCFirewallChaining


FPCFirewallChaining.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCFirewallChaining.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCFirewallChaining


FPCFirewallConnectionAdditionalInfo Object

Reserved for future use.


FPCFirewallSession Object

The FPCFirewallSession object represents a single firewall session. A firewall session is created each time a Firewall client or SecureNAT client makes a request. Application filters can create sessions by using the IFWXFirewall::CreatePrivateSession method. Server publishing rules also create sessions for requests they direct to published servers.

In ISA Management, sessions are shown in the Real Time Monitoring node.

The FPCFirewallSession object is a member of the FPCFirewallSessions collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCFirewallSession interface.

Methods

The following table lists the methods of the FPCFirewallSession object.

Method | Description
AbortSession | Stops all connections that have the user name and computer of the session, and removes the session from the collection.
Refresh | Reads the FPCFirewallSession objects by using a remote procedure call (RPC).

Properties

The following table lists the properties of the FPCFirewallSession object.

Property | Description
ClientComputerName | Gets the name of the client computer for this session.
ClientIpAddress | Gets the IP address of the client computer for this session.
UserName | Gets the user name for this session.
FirewallSessionConnections | Gets a pointer to the FPCFirewallSessionConnections collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSession.AbortSession Method

Stops all connections that have the user name and computer of the session.

VBScript Syntax[VBScript]

FPCFirewallSession.AbortSession()

C++ Syntax[C++]

HRESULT AbortSession();

Applies To

FPCFirewallSession


FPCFirewallSession.ClientComputerName Property

Gets the name of the client computer.

VBScript Syntax[VBScript]

[ sComputerName = ] FPCFirewallSession.ClientComputerName

C++ Syntax[C++]

HRESULT get_ClientComputerName(
  BSTR *psComputerName
);

Parameters

sComputerName
String that specifies the name of the client computer.

The property is read-only.

Applies To

FPCFirewallSession


FPCFirewallSession.ClientIpAddress Property

Gets the IP address of the client computer.

VBScript Syntax[VBScript]

[ sClientIpAddress = ] FPCFirewallSession.ClientIpAddress

C++ Syntax[C++]

HRESULT get_ClientIpAddress(
  BSTR *psClientIpAddress
);

Parameters

sClientIpAddress
String that specifies the IP address of the client computer.

The property is read-only.

Applies To

FPCFirewallSession


FPCFirewallSession.FirewallSessionConnections Property

Gets a pointer to the FPCFirewallSessionConnections collection.

VBScript Syntax[VBScript]

[ collFPCFirewallSessionConnections = ] FPCFirewallSession.FirewallSessionConnections

C++ Syntax[C++]

HRESULT get_FirewallSessionConnections(
  IFPCFirewallSessionConnections **pcollFPCFirewallSessionConnections
);

Parameters

collFPCFirewallSessionConnections
Reference to the FPCFirewallSessionConnections collection.

The property is read-only.

Applies To

FPCFirewallSession


FPCFirewallSession.Refresh Method

Reads all the properties of the FPCFirewallSession object from the Firewall service by using a remote procedure call (RPC).

VBScript Syntax[VBScript]

FPCFirewallSession.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Remarks

FPCFirewallSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. This method uses an RPC to query ISA services about its sessions because this information is dynamic.

Applies To

FPCFirewallSession


FPCFirewallSession.UserName Property

Gets the client Windows NT/Windows 2000 account.

VBScript Syntax[VBScript]

[sName = ] FPCFirewallSession.UserName

C++ Syntax[C++]

HRESULT get_UserName(
  BSTR *psName
);

Parameters

sName
String that specifies the Windows NT/Windows 2000 account of the client.

The property is read-only.

Applies To

FPCFirewallSession


FPCFirewallSessions Collection

The FPCFirewallSessions collection provides access to a group of FPCFirewallSession objects. This object is a property of the FPCServer object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCFirewallSessions interface.

Methods

The following table lists the methods of the FPCFirewallSessions collection.

Method | Description
Item | Retrieves the given FPCFirewallSession object from the collection.
Refresh | Reads all FPCFirewallSession objects that were not saved by means of an RPC call.

Properties

The following table lists the properties of the FPCFirewallSessions collection.

Property | Description
Count | Gets the number of FPCFirewallSession objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSessions.Count Property

Gets the number of FPCFirewallSession objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCFirewallSessions.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCFirewallSession objects.

The property is read-only.

Applies To

FPCFirewallSessions


FPCFirewallSessions.Item Method

Retrieves the given FPCFirewallSession object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCFirewallSessions.Item( vUserOrIndex, vClientComputer )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vUserOrIndex,
  VARIANT vClientComputer,
  IFPCFirewallSession **pvItem
);

Parameters

vUserOrIndex
Required. Variant that specifies the user name or one-based index of the object to retrieve.
vClientComputer
Optional. Variant that specifies the client computer.

Return Value

vItem
If successful, returns a reference to an object of type FPCFirewallSession; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCFirewallSessions


FPCFirewallSessions.Refresh Method

Reads all the FPCFirewallSession objects from the Firewall service by using a remote procedure call (RPC).

VBScript Syntax[VBScript]

FPCFirewallSessions.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Remarks

FPCFirewallSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. This method uses an RPC call query ISA services about its sessions because this information is dynamic.

Applies To

FPCFirewallSessions


FPCFirewallSessionConnection Object

A Windows Sockets (Winsock) session connection is defined by the client, the computer and the process. One or more connections may be established during a Winsock session. For example, if a client opens three instances of Microsoft Internet Explorer, he has opened three Winsock session connections.

The FPCFirewallSessionConnection object represents a single Winsock session connection. This object is a member of the FPCFirewallSessionConnections collection.

The FPCFirewallSessionConnection object is not represented in ISA Management.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCFirewallSessionConnection interface.

Methods

The following table lists the methods of the FPCFirewallSessionConnection object.

Method | Description
AbortConnection | Stops the connection.
Refresh | Reads the object configuration from the Firewall service by using a remote procedure call, discarding any changes to it that were not saved.

Properties

The following table lists the properties of the FPCFirewallSessionConnection object.

Property | Description
Duration | Gets the connection duration.
FirewallConnectionAdditionalInfo | Gets a pointer to the FPCFirewallConnectionAdditionalInfo object, which is reserved for future use.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSessionConnection.AbortConnection Method

Stops the connection.

VBScript Syntax[VBScript]

FPCFirewallSessionConnection.AbortConnection()

C++ Syntax[C++]

HRESULT AbortConnection();

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnection.Duration Property

Gets the connection duration. Each session may have more than one connection, and the connections may have different durations.

VBScript Syntax[VBScript]

[ lDuration = ] FPCFirewallSessionConnection.Duration

C++ Syntax[C++]

HRESULT get_Duration(
  long *plDuration
);

Parameters

lDuration
Long value that specifies the session duration.

The property is read-only.

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnection.FirewallConnectionAdditionalInfo Property

Gets a pointer to the FPCFirewallConnectionAdditionalInfo object, which is reserved for future use.

VBScript Syntax[VBScript]

[oFPCFirewallConnectionAdditionalInfo = ] FPCFirewallSessionConnection.FirewallConnectionAdditionalInfo

C++ Syntax[C++]

HRESULT get_FirewallConnectionAdditionalInfo(
  IFPCFirewallConnectionAdditionalInfo **poFPCFirewallConnectionAdditionalInfo
);

Parameters

oFPCFirewallConnectionAdditionalInfo
Reference to the FPCFirewallConnectionAdditionalInfo object, which is reserved for future use.

The property is read-only.

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnection.Refresh Method

Reads the object configuration from the Firewall service by using a remote procedure call (RPC), discarding any changes to it that were not saved.

VBScript Syntax[VBScript]

FPCFirewallSessionConnection.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCFirewallSessionConnection


FPCFirewallSessionConnections Collection

The FPCFirewallSessionConnections collection provides access to a group of FPCFirewallSessionConnection objects. This object is a property of the FPCFirewallSession object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCFirewallSessionConnections interface.

Methods

The following table lists the methods of the FPCFirewallSessionConnections collection.

Method | Description
Item | Retrieves the given FPCFirewallSessionConnection object from the collection.
Refresh | Reads all the FPCFirewallSessionConnection objects from the Firewall service by using a remote procedure call (RPC), discarding any changes to the objects that were not saved.

Properties

The following table lists the properties of the FPCFirewallSessionConnections collection.

Property | Description
Count | Gets the number of FPCFirewallSessionConnection objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFirewallSessionConnections.Count Property

Gets the number of FPCFirewallSessionConnection objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCFirewallSessionConnections.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCFirewallSessionConnection objects.

The property is read-only.

Applies To

FPCFirewallSessionConnections


FPCFirewallSessionConnections.Item Method

Retrieves the given FPCFirewallSessionConnection object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCFirewallSessionConnections.Item ( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  IFPCFirewallSessionConnection **pvItem
);

Parameters

lIndex
Required. Index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCFirewallSessionConnection; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCFirewallSessionConnections


FPCFirewallSessionConnections.Refresh Method

Reads all the FPCFirewallSessionConnection objects from the Firewall service by using a remote procedure call (RPC), discarding any changes to the objects that were not saved.

VBScript Syntax[VBScript]

FPCFirewallSessionConnections.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCFirewallSessionConnections


FPCFTPCacheConfiguration Object

The FPCFTPCacheConfiguration object provides access to the FTP cache configuration parameters of an ISA Server. The objects FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration provide access to all ISA cache configuration settings. These three objects are accessed through properties of the FPCCacheConfiguration object, which serves as a container for the three.

The FPCFTPCacheConfiguration object is a property of an FPCCacheConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCFTPCacheConfiguration interface.

Methods

The following table lists the methods of the FPCFTPCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
ResetToDefaults | Discards any changes made to the FTP cache configuration and reverts to the default cache configuration.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCFTPCacheConfiguration object.

Property | Description
FTPEnable | Gets or sets whether caching of FTP replies is enabled or disabled.
FTPTTLUnits | Gets or sets the time units in which the Time to Live (TTL) is measured.
FTPTTLValue | Gets or sets the fixed Time to Live (TTL) for FTP cached files.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCFTPCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCFTPCacheConfiguration.FTPEnable Property

Gets or sets whether caching of FTP replies is enabled or disabled.

VBScript Syntax[VBScript]

FPCFTPCacheConfiguration.FTPEnable [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_FTPEnable(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_FTPEnable(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether caching of FTP replies is enabled.

The property is read-write.

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.FTPTTLUnits Property

Gets or sets the time units in which the Time to Live (TTL) is measured. The time units can be seconds, minutes, hours, days or weeks.

VBScript Syntax[VBScript]

FPCFTPCacheConfiguration.FTPTTLUnits [ = TimeUnits ]

C++ Syntax[C++]

HRESULT get_FTPTTLUnits(
  FpcTimeScale TimeUnits
);

HRESULT put_FTPTTLUnits(
  FpcTimeScale TimeUnits
);

Parameters

TimeUnits
Time units in which the TTL is measured. Can have a value from the FpcTimeScale enumerated type.

The property is read-write.

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.FTPTTLValue Property

Gets or sets the fixed Time to Live (TTL) for FTP cached files.

VBScript Syntax[VBScript]

FPCFTPCacheConfiguration.FTPTTLValue [ = lTTL ]

C++ Syntax[C++]

HRESULT get_FTPTTLValue(
  long lTTL
);

HRESULT put_FTPTTLValue(
  long lTTL
);

Parameters

lTTL
Long value that specifies the TTL.

The property is read-write.

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCFTPCacheConfiguration.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.ResetToDefaults Method

Discards any changes made to the cache configuration and reverts to the default cache configuration, including a TTL of 1440 minutes.

VBScript Syntax[VBScript]

FPCFTPCacheConfiguration.ResetToDefaults()

C++ Syntax[C++]

HRESULT ResetToDefaults();

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCFTPCacheConfiguration.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCFTPCacheConfiguration


FPCFTPCacheConfiguration.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCFTPCacheConfiguration object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCFTPCacheConfiguration.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCFTPCacheConfiguration


FPCHTTPCacheConfiguration Object

The FPCHTTPCacheConfiguration object provides access to the HTTP cache configuration parameters of an ISA server. The objects FPCActiveCacheConfiguration, FPCHTTPCacheConfiguration, and FPCFTPCacheConfiguration provide access to all ISA cache configuration settings. These three objects are accessed through properties of the FPCCacheConfiguration object, which serves as a container for the three.

The FPCHTTPCacheConfiguration object is a property of an FPCCacheConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCHTTPCacheConfiguration interface.

Methods

The following table lists the methods of the FPCHTTPCacheConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
ResetToDefaults | Discards any changes made to the HTTP cache configuration and reverts to the default cache configuration.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCHTTPCacheConfiguration object.

Property | Description
AgeFactor | Gets or sets the age factor for determining the Time to Live (TTL) of cached HTTP requests.
CacheNon200Responses | Gets or sets whether caching of replies whose responses were not OK (200) is enabled or disabled.
CacheWithNoLastModDate | Gets or sets whether caching of replies that are missing the modification date is enabled or disabled.
ExpirationPolicy | Gets or sets preset values for the cache policy.
HTTPEnable | Gets or sets whether caching of HTTP replies is enabled or disabled.
MaxIntervalUnits | Gets or sets the time units in which the MaxIntervalValue property is expressed.
MaxIntervalValue | Gets or sets the maximum TTL interval of cached objects originating from HTTP requests.
MinInterval | Gets or sets the minimum TTL interval of cached objects originating from HTTP requests.
MinIntervalUnits | Gets or sets the time units in which the MinInterval property is expressed.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCHTTPCacheConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCHTTPCacheConfiguration.AgeFactor Property

Gets or sets the age factor for determining the Time to Live (TTL) of cached HTTP requests. The age factor establishes a TTL as a percentage of the Web object's age, based on the time it was created or modified. This property is only applicable when FPCHTTPCacheConfiguration.ExpirationPolicy is set to fpcCachePolicyCustom.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.AgeFactor [ = lFactor ]

C++ Syntax[C++]

HRESULT get_AgeFactor(
  long *plFactor
);

HRESULT put_AgeFactor(
  long lFactor
);

Parameters

lFactor
Long value that specifies the TTL age factor.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.CacheNon200Responses Property

Gets or sets whether caching of replies whose responses were not OK (200) is enabled or disabled.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.CacheNon200Responses [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_CacheNon200Responses(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_CacheNon200Responses(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether caching of replies whose responses were not OK is enabled.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.CacheWithNoLastModDate Property

Gets or sets whether caching of replies that are missing the modification date is enabled or disabled.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.CacheWithNoLastModDate [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_CacheWithNoLastModDate(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_CacheWithNoLastModDate(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether caching of replies that are missing the modification date is enabled.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.ExpirationPolicy Property

Gets or sets preset values for the cache policy that define how soon cached Web pages expire. Setting this property affects the AgeFactor, MaxIntervalValue, and MinInterval properties.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.ExpirationPolicy [ = Policy ]

C++ Syntax[C++]

HRESULT get_ExpirationPolicy(
  FpcCacheExpirationPolicy *pPolicy
);

HRESULT put_ExpirationPolicy(
  FpcCacheExpirationPolicy Policy
);

Parameters

Policy
A value from the FpcCacheExpirationPolicy enumerated type.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.HTTPEnable Property

Gets or sets whether caching of HTTP replies is enabled or disabled.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.HTTPEnable [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_HTTPEnable(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_HTTPEnable(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether caching of HTTP replies is enabled.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.MaxIntervalUnits Property

Gets or sets the time units in which the MaxIntervalValue property is expressed, when the ExpirationPolicy property is set to fpcCachePolicyCustom. Can be seconds, minutes, hours, days or weeks.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.MaxIntervalUnits [ = Units ]

C++ Syntax[C++]

HRESULT get_MaxIntervalUnits(
  FpcTimeScale *pUnits
);

HRESULT put_MaxIntervalUnits(
  FpcTimeScale Units
);

Parameters

Units
Value from the FpcTimeScale enumerated type.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.MaxIntervalValue Property

Gets or sets the maximum Time-to-Live (TTL) interval of cached objects originating from HTTP requests, when the ExpirationPolicy property is set to fpcCachePolicyCustom.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.MaxIntervalValue [ = lInterval ]

C++ Syntax[C++]

HRESULT get_MaxIntervalValue(
  long *plInterval
);

HRESULT put_MaxIntervalValue(
  long lInterval
);

Parameters

lInterval
Long value that specifies the maximum TTL interval. The interval is specified in units determined by the value of the MaxIntervalUnits property.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.MinInterval Property

Gets or sets the minimum Time-to-Live (TTL) interval of cached objects originating from HTTP requests, when the ExpirationPolicy property is set to fpcCachePolicyCustom.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.MinInterval [= lInterval ]

C++ Syntax[C++]

HRESULT get_MinInterval(
  long lInterval
);

HRESULT put_MinInterval(
  long lInterval
);

Parameters

lInterval
Long value that specifies the minimum TTL interval, in minutes.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.MinIntervalUnits Property

Gets or sets the time units in which the MinInterval property is expressed, when the ExpirationPolicy property is set to fpcCachePolicyCustom. Can be seconds, minutes, hours, days or weeks.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.MinIntervalUnits [ = Units ]

C++ Syntax[C++]

HRESULT get_MinIntervalUnits(
  FpcTimeScale *pUnits
);

HRESULT put_MinIntervalUnits(
  FpcTimeScale Units
);

Parameters

Units
Value from the FpcTimeScale enumerated type.

The property is read-write.

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.ResetToDefaults Method

Discards any changes made to the cache configuration and reverts to the default cache configuration.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.ResetToDefaults()

C++ Syntax[C++]

HRESULT ResetToDefaults();

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCHTTPCacheConfiguration.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCHTTPCacheConfiguration


FPCHTTPCacheConfiguration.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCHTTPCacheConfiguration object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCHTTPCacheConfiguration.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCHTTPCacheConfiguration


FPCIpPacketFilter Object

The FPCIpPacketFilter object represents a single IP packet filter object of an ISA array, either an allowing or blocking filter. An IP packet filter monitors all network traffic to determine whether the packets can be communicated. If the packet passes through the filter, the data is then passed up to the application layer.

FPCIpPacketFilter is a member of the FPCIpPacketFilters collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCIpPacketFilter interface.

Methods

The following table lists the methods of the FPCIpPacketFilter object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetLocalHost | Sets the type and IP values of the local host.
SetRemoteHost | Sets the type and IP values of the remote host.

Properties

The following table lists the properties of the FPCIpPacketFilter object.

Property | Description
AllServers | Gets or sets whether the filter applies to all the servers in the array.
Description | Gets or sets the description of the IP packet filter.
Enabled | Gets or sets whether the filter is enabled.
FilterMode | Gets the kind of filter, either an allowing or blocking filter.
FilterType | Gets or sets the type of the filter.
ICMPCodeNumber | Gets or sets the Internet Control Message Protocol (ICMP) code number used by the filter.
ICMPCodeOption | Gets or sets the kind of Internet Control Message Protocol (ICMP) code used by the filter.
ICMPTypeNumber | Gets or sets the Internet Control Message Protocol (ICMP) type number used by the filter.
ICMPTypeOption | Gets or sets the kind of Internet Control Message Protocol (ICMP) type attribute used by the filter.
LocalHostIPAddress | Gets the IP address of the local host.
LocalHostIPMask | Gets the IP mask of the local host.
LocalHostType | Gets the type of local host used by the filter.
LocalPortNumber | Gets or sets the local port number used by the filter.
LocalPortType | Gets or sets the type of local port used by the filter.
LogMatchingPackets | Gets or sets whether the filter will log packets that match its parameters.
Name | Gets or sets the name of the IP packet filter.
PacketDirection | Gets or sets the direction of packets monitored by the filter.
ProtocolNumber | Gets or sets the IP protocol monitored by the filter.
RemoteHostIPAddress | Gets the IP address of the remote host.
RemoteHostIPMask | Gets the IP mask of the remote host.
RemoteHostType | Gets the type of remote host used by the filter.
RemotePortNumber | Gets or sets the remote port number used by the filter.
RemotePortType | Gets or sets the type of remote port used by the filter.
ServerName | Gets or sets the name of the specific server to which this filter applies.
UDPPacketDirection | Gets or sets the direction of UDP packets for this filter.
VendorParametersSets | Gets a reference to an object used to access a vendor's data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCIpPacketFilter.AllServers Property

Gets or sets whether the filter applies to all servers in the array.

Note This property is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

VBScript Syntax[VBScript]

FPCIpPacketFilter.AllServers [ = bApplies ]

C++ Syntax[C++]

HRESULT get_AllServers(
  VARIANT_BOOL *pbApplies
);

HRESULT put_AllServers(
  VARIANT_BOOL bApplies
);

Parameters

bApplies
Boolean value that specifies whether the filter applies to all servers (TRUE), or only to the server whose name can be found through the ServerName property (FALSE).

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Description Property

Gets or sets the description of the IP packet filter.

VBScript Syntax[VBScript]

FPCIpPacketFilter.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the IP packet filter description.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Enabled Property

Gets or sets whether the filter is enabled.

Note If the enterprise administrator forces packet filtering through the FPCEnterprise.ForcePacketFiltering property, an array administrator will not be able to disable packet filtering through the FPCIpPacketFilter.Enabled property.

VBScript Syntax[VBScript]

FPCIpPacketFilter.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled

Boolean value that specifies whether the filter is enabled.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.FilterMode Property

Gets the kind of the filter, either an allowing or blocking filter.

VBScript Syntax[VBScript]

[ PFFilterMode = ] FPCIpPacketFilter.FilterMode

C++ Syntax[C++]

HRESULT get_FilterMode(
  FpcPFFilterMode *pPFFilterMode
);

Parameters

PFFilterMode
Filter mode. It can have a value from the FpcPfFilterMode enumerated type.

The property is read-only. The filter mode is set when adding a new packet filter by using the FPCIpPacketFilters.Add method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.FilterType Property

Gets or sets the type of filter, such as a predefined or custom type.

VBScript Syntax[VBScript]

FPCIpPacketFilter.FilterType [ = PFFilterType ]

C++ Syntax[C++]

HRESULT get_FilterType(
  FpcPFFilterType *pPFFilterType
);

HRESULT put_FilterType(
  FpcPFFilterType PFFilterType
);

Parameters

PFFilterType
Filter type. It can have a value from the FpcPfFilterType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPCodeNumber Property

Gets or sets the Internet Control Message Protocol (ICMP) code number used by the filter. It can have a value from 0 to 255. ICMP code is a subdescriptor of the ICMP type.

VBScript Syntax[VBScript]

FPCIpPacketFilter.ICMPCodeNumber[ = lICMPCodeNumber ]

C++ Syntax[C++]

HRESULT get_ICMPCodeNumber(
  long *plICMPCodeNumber
);

HRESULT put_ICMPCodeNumber(
  long lICMPCodeNumber
);

Parameters

lICMPCodeNumber
Long value that specifies the ICMP code number.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPCodeOption Property

Gets or sets the kind of Internet Control Message Protocol (ICMP) code used by the filter.

VBScript Syntax[VBScript]

FPCIpPacketFilter.ICMPCodeOption [ = PFICMPCodeOption ]

C++ Syntax[C++]

HRESULT get_ICMPCodeOption(
  FpcPFICMPCodeOptions *pPFICMPCodeOption
);

HRESULT put_ICMPCodeOption(
  FpcPFICMPCodeOptions PFICMPCodeOption
);

Parameters

PFICMPCodeOption
ICMP code option. It can have a value from the FpcPFICMPCodeOptions enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPTypeNumber Property

Gets or sets the Internet Control Message Protocol (ICMP) type number used by the filter. It can have a value from 0 to 255.

VBScript Syntax[VBScript]

FPCIpPacketFilter.ICMPTypeNumber[ = lICMPTypeNumber ]

C++ Syntax[C++]

HRESULT get_ICMPTypeNumber(
  long *plICMPTypeNumber
);

HRESULT put_ICMPTypeNumber(
  long lICMPTypeNumber
);

Parameters

lICMPTypeNumber
Long value that specifiies the ICMP type number.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ICMPTypeOption Property

Gets or sets the kind of Internet Control Message Protocol (ICMP) type attribute used by the filter.

VBScript Syntax[VBScript]

FPCIpPacketFilter.ICMPTypeOption [ = PFICMPTypeOption ]

C++ Syntax[C++]

HRESULT get_ICMPTypeOption(
  FpcPFICMPTypeOptions *pPFICMPTypeOption
);

HRESULT put_ICMPTypeOption(
  FpcPFICMPTypeOptions PFICMPTypeOption
);

Parameters

PFICMPTypeOption
ICMP type option. It can have a value from the FpcPFICMPTypeOptions enumerated type:

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalHostIPAddress Property

Gets the IP address of the local host.

VBScript Syntax[VBScript]

[ sLocalHostIPAddress = ] FPCIpPacketFilter.LocalHostIPAddress

C++ Syntax[C++]

HRESULT get_LocalHostIPAddress(
  BSTR *psLocalHostIPAddress
);

Parameters

sLocalHostIPAddress
String that specifies the local host IP address.

The property is read-only.

Remarks

This property is read-only, but the value of LocalHostIPAddress can be set by using the SetLocalHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalHostIPMask Property

Gets the IP mask of the local host when the host contains a range of computers.

VBScript Syntax[VBScript]

[ sLocalHostIPMask = ] FPCIpPacketFilter.LocalHostIPMask

C++ Syntax[C++]

HRESULT get_LocalHostIPMask(
  BSTR *psLocalHostIPMask
);

Parameters

sLocalHostIPMask
Returns a string value that specifies the local host IP mask.

The property is read-only.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalHostType Property

Gets the type of local host used by the filter.

VBScript Syntax[VBScript]

[ PFLocalHostType = ] FPCIpPacketFilter.LocalHostType

C++ Syntax[C++]

HRESULT get_LocalHostType(
  FpcPFLocalHostType *pPFLocalHostType
);

Parameters

PFLocalHostType
The local host type. It can have a value from the FpcPFLocalHostType enumerated type.

The property is read-only.

Remarks

This property is read-only, but the value of LocalHostType can be set by using the SetLocalHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LocalPortNumber Property

Gets or sets the local port number used by the filter, within the allowed port range of 1 to 65535.

VBScript Syntax[VBScript]

FPCIpPacketFilter.LocalPortNumber[ = lLocalPortNumber ]

C++ Syntax[C++]

HRESULT get_LocalPortNumber(
  long *plLocalPortNumber
);

HRESULT put_LocalPortNumber(
  long lLocalPortNumber
);

Parameters

lLocalPortNumber
Long value that specifies the local port number.

The property is read-write.

Remarks

When the RemotePortType property is set to the fpcPfAnyPort or the fpcPfDynamicPort value of the FpcPFLocalPortType enumerated type, this property becomes meaningless.

Applies To

FPCIpPacketFilter

See also

LocalPortType


FPCIpPacketFilter.LocalPortType Property

Gets or sets the type of local port. This port can be allowed or blocked by the filter according to the kind of filter (allowing or blocking).

VBScript Syntax[VBScript]

FPCIpPacketFilter.LocalPortType [ = PFLocalPortType ]

C++ Syntax[C++]

HRESULT get_LocalPortType(
  FpcPFLocalPortType *pPFLocalPortType
);

HRESULT put_LocalPortType(
  FpcPFLocalPortType PFLocalPortType
);

Parameters

PFLocalPortType
The local port type. It can have a value from the FpcPFLocalPortType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.LogMatchingPackets Property

Gets or sets whether the filter will log packets that match its parameters. This applies to blocking filters only.

VBScript Syntax[VBScript]

FPCIpPacketFilter.LogMatchingPackets [ = bLogMatchingPackets ]

C++ Syntax[C++]

HRESULT get_LogMatchingPackets(
  VARIANT_BOOL *pbLogMatchingPackets
);

HRESULT put_LogMatchingPackets(
  VARIANT_BOOL bLogMatchingPackets
);

Parameters

bLogMatchingPackets
Boolean value that specifies whether the filter will log packets that it matches.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Name Property

Gets or sets the name of the IP packet filter.

VBScript Syntax[VBScript]

FPCIpPacketFilter.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the IP packet filter name.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.PacketDirection Property

Gets or sets the direction of packets that are allowed or blocked, depending on the filter mode.

VBScript Syntax[VBScript]

FPCIpPacketFilter.PacketDirection [ = PacketDirectionType ]

C++ Syntax[C++]

HRESULT get_PacketDirection(
  FpcPFDirectionType *pPacketDirectionType
);

HRESULT put_PacketDirection(
  FpcPFDirectionType PacketDirectionType
);

Parameters

PacketDirectionType
The packet direction. It can have a value from the FpcPFDirectionType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ProtocolNumber Property

Gets or sets the Internet Protocol (IP) monitored by the filter. (The protocol can be TCP, UDP, ICMP, or another type.)

VBScript Syntax[VBScript]

FPCIpPacketFilter.ProtocolNumber [ = FpcProtocolNumber ]

C++ Syntax[C++]

HRESULT get_ProtocolNumber(
  long *pFpcProtocolNumber
);

HRESULT put_ProtocolNumber(
  long FpcProtocolNumber
);

Parameters

FpcProtocolNumber
The protocol number. It can be an IP protocol number of the range 0-255, or have a value from the FpcPFProtocolType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCIpPacketFilter.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemoteHostIPAddress Property

Gets the IP address of the remote host.

VBScript Syntax[VBScript]

[ sRemoteHostIPAddress = ] FPCIpPacketFilter.RemoteHostIPAddress

C++ Syntax[C++]

HRESULT get_RemoteHostIPAddress(
  BSTR *psRemoteHostIPAddress
);

Parameters

sRemoteHostIPAddress
String specifying the remote host IP address.

The property is read-only.

Remarks

This property is read-only, but RemoteHostIPAddress can be set by using the SetRemoteHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemoteHostIPMask Property

Gets the Internet Protocol (IP) mask of the remote host, but only when a mask is needed, as in the case of a subnet remote host.

VBScript Syntax[VBScript]

[ sRemoteHostIPMask = ]  FPCIpPacketFilter.RemoteHostIPMask

C++ Syntax[C++]

HRESULT get_RemoteHostIPMask(
  BSTR *psRemoteHostIPMask
);

Parameters

sRemoteHostIPMask
String value that specifies the remote host IP mask.

The property is read-only.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemoteHostType Property

Gets the type of remote host used by the filter.

VBScript Syntax[VBScript]

[ PFRemoteHostType = ] FPCIpPacketFilter.RemoteHostType

C++ Syntax[C++]

HRESULT get_RemoteHostType(
  FpcPFRemoteHostType *pPFRemoteHostType
);

Parameters

PFRemoteHostType
The remote host type. It can have a value of the FpcPFRemoteHostType enumerated type.

The property is read-only.

Remarks

This property is read-only, but RemoteHostType can be set by using the SetRemoteHost method.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemotePortNumber Property

Gets or sets the remote port number used by the filter, within the allowed port range of 1 to 65535.

VBScript Syntax[VBScript]

FPCIpPacketFilter.RemotePortNumber [ = lRemotePortNumber ]

C++ Syntax[C++]

HRESULT get_RemotePortNumber(
  long *plRemotePortNumber
);

HRESULT put_RemotePortNumber(
  long lRemotePortNumber
);

Parameters

lRemotePortNumber
Long value that specifies the remote port number.

The property is read-write.

Remarks

When the RemotePortType property is set to fpcPfAnyPort, RemotePortNumber becomes meaningless.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.RemotePortType Property

Gets or sets the type of remote port. This port can be allowed or blocked by the filter.

VBScript Syntax[VBScript]

FPCIpPacketFilter.RemotePortType [ = PFRemotePortType ]

C++ Syntax[C++]

HRESULT get_RemotePortType(
  FpcPFRemotePortType *pPFRemotePortType
);

HRESULT put_RemotePortType(
  FpcPFRemotePortType PFRemotePortType
);

Parameters

PFRemotePortType
The remote port type. It can have a value from the FpcPFRemotePortType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCIpPacketFilter.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.ServerName Property

Gets or sets the name of the specific server for which this filter applies. This property is only valid when AllServers is not set to TRUE, in which case the filter applies to all servers in the array.

VBScript Syntax[VBScript]

FPCIpPacketFilter.ServerName [ = sName ]

C++ Syntax[C++]

HRESULT get_ServerName(
  BSTR *psName
);

HRESULT put_ServerName(
  BSTR sName
);

Parameters

sName
String that specifies the server name.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.SetLocalHost Method

Sets the type and IP values of the local host.

VBScript Syntax[VBScript]

FPCIpPacketFilter.SetLocalHost( LocalHostType, sNewIPAddress, sNewIPMask )

C++ Syntax[C++]

HRESULT SetLocalHost(
  FpcPFLocalHostType LocalHostType,
  BSTR sNewIPAddress,
  BSTR sNewIPMask
);

Parameters

LocalHostType
The local host type. It can have a value of the FpcPFLocalHostType enumerated type.
sNewIPAddress
Optional. The name or IP address of the local host.
sNewIPMask
Optional. String that specifies the mask of the local host.

Applies To

FPCIpPacketFilter

See Also

LocalHostType, LocalHostIPAddress


FPCIpPacketFilter.SetRemoteHost Method

Sets the type and IP values of the remote host.

VBScript Syntax[VBScript]

FPCIpPacketFilter.SetRemoteHost( RemoteHostType, sNewIPAddress, sNewIPMask )

C++ Syntax[C++]

HRESULT SetRemoteHost(
  FpcPFRemoteHostType RemoteHostType,
  BSTR sNewIPAddress,
  BSTR sNewIPMask
);

Parameters

RemoteHostType
The local host type. It can have a value of the FpcPFRemoteHostType enumerated type.
sNewIPAddress
Optional. The name or IP address of the remote host.
sNewIPMask
Optional. String that specifies the mask of the remote host.

Applies To

FPCIpPacketFilter

See Also

RemoteHostType, RemoteHostIPAddress


FPCIpPacketFilter.UDPPacketDirection Property

Gets or sets the direction for UDP packets that are allowed or blocked, depending on the filter mode.

VBScript Syntax[VBScript]

FPCIpPacketFilter.UDPPacketDirection [ = UDPPacketDirectionType ]

C++ Syntax[C++]

HRESULT get_UDPPacketDirection(
  FpcPFUDPDirectionType *pUDPPacketDirectionType
);

HRESULT put_UDPPacketDirection(
  FpcPFUDPDirectionType UDPPacketDirectionType
);

Parameters

UDPPacketDirectionType
The direction of the UDP packet. It can have a value from the FpcPFUDPDirectionType enumerated type.

The property is read-write.

Applies To

FPCIpPacketFilter


FPCIpPacketFilter.VendorParametersSets Property

Gets a reference to an object that is used to access a vendor's data.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCIpPacketFilter.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCIpPacketFilter


FPCIpPacketFilters Collection

The FPCIpPacketFilters collection provides access to a group of IP packet filter objects in an ISA array. An IP packet filter monitors all network traffic to determine whether the packets can be communicated. If the packet passes through the filter, the data is then passed up to the application layer. An individual IP packet filter is either an allowing or blocking filter. Allowing filters permit communication between specified IP addresses by using the specified protocols and ports. Blocking filters block communication between specified IP addresses by using the specified protocols and ports.

This collection is a property of an FPCArrayPolicy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCIpPacketFilters interface.

Methods

The following table lists the methods of the FPCIpPacketFilters collection.

Method | Description
Add | Creates a new FPCIpPacketFilter object in the collection and returns a reference to it.
Item | Retrieves the given FPCIpPacketFilter object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an IP packet filter object from the collection.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCIpPacketFilters collection.

Property | Description
Count | Gets the number of FPCIpPacketFilter objects in the collection.
Enabled | Gets or sets whether IP packet filtering is enabled.
EnablePPTP | Gets or sets whether Point-to-Point Tunneling (PPTP) is enabled.
IntrusionDetectionEnabled | Gets or sets whether the Intrusion Detection setting is enabled.
IpFragmentsFilteringEnabled | Gets or sets whether IP fragment filters are enabled.
IpHalfScanDetectionEnabled | Gets or sets whether Internet Protocol (IP) half-scan attacks are detected and generate an event.
IpOptionPacketFilteringEnabled | Gets or sets whether IP packet filters are enabled.
IpRoutingEnabled | Gets or sets whether Internet Protocol (IP) routing is enabled.
LandAttackDetectionEnabled | Gets or sets whether land attacks are detected and generate an event.
LogPacketsFromAllowFilters | Gets or sets whether packets from allow filters are logged.
PingOfDeathDetectionEnabled | Gets or sets whether ping-of-death attacks are detected and generate an event.
PortScanDetectionAllPortsThreshold | Gets or sets, if detection of port scan attacks is enabled, the total number of ports that can be scanned before ISA generates an alert.
PortScanDetectionEnabled | Gets or sets whether port scan attacks are detected and generate an event.
PortScanDetectionWellKnownPortsThreshold | If detection of port scan attacks is enabled, this property gets or sets the total number of well-known ports that can be scanned before ISA generates an alert.
UdpBombDetectionEnabled | Gets or sets whether User Datagram Protocol (UDP) bomb attacks are detected and generate an event.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCIpPacketFilters collection's storage.
WinOutOfBandDetectionEnabled | Gets or sets whether Windows out-of-band attacks are detected and generate an event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCIpPacketFilters.Add Method

Creates a new FPCIpPacketFilter object in the collection and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCIpPacketFilter = ] FPCIpPacketFilters.Add( sName, FilterMode )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  FpcPFFilterMode FilterMode,
  IFPCIpPacketFilter **ppoFPCIpPacketFilter
);

Parameters

sName
Required. String that specifies the name of the new filter.
FilterMode
Filter mode. This can have a value from the FpcPfFilterMode enumerated type.

Return Value

oFPCIpPacketFilter
Returns a reference to the new FPCIpPacketFilter object.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Count Property

Gets the number of FPCIpPacketFilter objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCIpPacketFilters.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCIpPacketFilter objects.

The property is read-only.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Enabled Property

Gets or sets whether IP packet filtering is enabled. If the enterprise administrator forces packet filtering through the FPCEnterprise.ForcePacketFiltering property, an array administrator will not be able to disable packet filtering through this Property.

Note When you've changed the setting by using the Enabled property, and have saved changes by using the Save method, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

VBScript Syntax[VBScript]

FPCIpPacketFilters.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
 VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
 VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether IP packet filtering is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.EnablePPTP Property

Gets or sets whether Point-to-Point Tunneling (PPTP) is enabled.

VBScript Syntax[VBScript]

FPCIpPacketFilters.EnablePPTP [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_EnablePPTP(
 VARIANT_BOOL *pbEnabled
);

HRESULT put_EnablePPTP(
 VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether Point-to-Point tunneling is enabled.

The property is read-write.

Remarks

You can configure Microsoft Internet Security and Acceleration (ISA) Server to allow internal clients to access servers on the Internet by using Point-to-Point Tunneling Protocol (PPTP). If you allow PPTP access, all secure network address translation (SecureNAT) and Firewall clients are always allowed to access any server on the Internet by using PPTP.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IntrusionDetectionEnabled Property

Gets or sets whether the intrusion detection setting is enabled. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

VBScript Syntax[VBScript]

FPCIpPacketFilters.IntrusionDetectionEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_IntrusionDetectionEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_IntrusionDetectionEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether intrusion detection is enabled.

The property is read-write.

Remarks

ISA Server features intrusion detection, which identifies when an attack is attempted against your network and then performs a set of configured actions, or alerts, in case of an attack. Intrusion detection functionality based on technology from Internet Security Systems, Inc., Atlanta, GA, USA, www.iss.net.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpFragmentsFilteringEnabled Property

Gets or sets whether IP fragment filtering is enabled. If IP fragment filtering is enabled, datagram fragments are filtered. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

VBScript Syntax[VBScript]

FPCIpPacketFilters.IpFragmentsFilteringEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_IPFragmentsFilteringEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_IPFragmentsFilteringEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether IP fragment filtering is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpHalfScanDetectionEnabled Property

Gets or sets whether Internet Protocol (IP) half-scan attacks are detected and generate an event. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

VBScript Syntax[VBScript]

FPCIpPacketFilters.IpHalfScanDetectionEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_IPHalfScanDetectionEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_IPHalfScanDetectionEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether detection of IP half scan attacks is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpOptionPacketFilteringEnabled Property

Gets or sets whether this filtering option is enabled. IP option filtering is the filtering of all IP traffic with "IP options" added to the IP header. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

VBScript Syntax[VBScript]

FPCIpPacketFilters.IpOptionPacketFilteringEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_IpOptionPacketFilteringEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_IpOptionPacketFilteringEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether filtering IP packets with "IP options" is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.IpRoutingEnabled Property

Gets or sets whether Internet Protocol (IP) routing is enabled.

Note It is not recommended to enable IP routing without enabling packet filtering.

When you enable packet filtering on Microsoft Internet Security and Acceleration (ISA) Server, all packets on the external interface are dropped unless they are explicitly allowed, either statically, by Internet Protocol (IP) packet filters, or dynamically, by access policy or publishing rules.

The opposite scenario is configured when you enable routing on ISA Server without enabling packet filtering. In that case, ISA Server simply routes all traffic between the Internet and your corporate network. In other words, ISA Server acts as a router, a device that connects disjointed networks by forwarding packets between them. This is not a recommended scenario for ISA Server.

By enabling both packet filtering and routing, you enjoy the benefits of strict policy enforcement at the packet filter level, as well as routing capabilities for secondary connections. It is recommended that you enable filtering and routing on ISA Server, since this combines the security of packet filtering with the performance enhancement of routing.

VBScript Syntax[VBScript]

FPCIpPacketFilters.IpRoutingEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_IpRoutingEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_IpRoutingEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether IP routing is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Item Method

Retrieves the given FPCIpPacketFilter object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCIpPacketfilters.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCIpPacketFilter **pvItem
);

Parameters

vIndex
Required. Name or index that specifies the one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCIpPacketFilter; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.LandAttackDetectionEnabled Property

Gets or sets whether land attacks are detected and generate an event. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

A land attack is one in which a transmission control protocol (TCP) SYN packet was sent with a spoofed source IP address and port number that matches that of the destination IP address and port.

VBScript Syntax[VBScript]

FPCIpPacketFilters.LandAttackDetectionEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_LandAttackDetectionEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_LandAttackDetectionEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether detection of land attacks is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.LogPacketsFromAllowFilters Property

Gets or sets whether packets from allow filters are logged.

Note Logging allowed packets and blocked packets causes a considerable load on the server.

VBScript Syntax[VBScript]

FPCIpPacketFilters.LogPacketsFromAllowFilters [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_LogPacketsFromAllowFilters(
  VARIANT_BOOL *pbEnabled

HRESULT put_LogPacketsFromAllowFilters(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether logging of packets from allow filters is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PingOfDeathDetectionEnabled Property

Gets or sets whether ISA will detect ping-of-death attacks and generate an event. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

A ping of death attack is one in which a large amount of information was appended to an ICMP echo request (ping) packet.

VBScript Syntax[VBScript]

FPCIpPacketFilters.PingOfDeathDetectionEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_PingOfDeathDetectionEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_PingOfDeathDetectionEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether detection of ping-of-death attacks is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PortScanDetectionAllPortsThreshold Property

Gets or sets, if detection of port scan attacks is enabled, the total number of ports that can be scanned before ISA generates an alert. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

VBScript Syntax[VBScript]

FPCIpPacketFilters.PortScanDetectionAllPortsThreshold [ = lPortTreshold ]

C++ Syntax[C++]

HRESULT get_PortScanDetectionAllPortsThreshold(
  long *plPortTreshold
);

HRESULT put_PortScanDetectionAllPortsThreshold(
  long lPortTreshold
);

Parameters

lPortTreshold
Long value that specifies the number of ports.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PortScanDetectionEnabled Property

Gets or sets whether port scan attacks are detected and generate an event. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

A port scan attack is one in which an attempt is made to scan ports on a computer to detect services running on those ports.

VBScript Syntax[VBScript]

FPCIpPacketFilters.PortScanDetectionEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_PortScanDetectionEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_PortScanDetectionEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether detection of port scan attacks is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.PortScanDetectionWellKnownPortsThreshold Property

If detection of port scan attacks is enabled, this property gets or sets the total number of well-known ports that can be scanned before ISA generates an alert.

VBScript Syntax[VBScript]

FPCIpPacketFilters.PortScanDetectionWellKnownPortsThreshold [ = lWellKnownThreshold ]

C++ Syntax[C++]

HRESULT get_PortScanDetectionWellKnownPortsThreshold(
  long *plWellKnownThreshold
);

HRESULT put_PortScanDetectionWellKnownPortsThreshold(
  long lWellKnownThreshold
);

Parameters

lWellKnownThreshold
Long value that specifies the number of well-known ports.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCIpPacketFilters.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.Remove Method

Removes an IP packet filter object from the collection.

VBScript Syntax[VBScript]

FPCIpPacketFilters.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCIpPacketFilters

See Also

FPCIpPacketFilter


FPCIpPacketFilters.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCIpPacketFilters.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.UdpBombDetectionEnabled Property

Gets or sets whether ISA will detect User Datagram Protocol (UDP) bomb attacks and generate an event. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

A UDP Bomb Attack is one in which an attempt was made to send an illegal User Datagram Protocol (UDP) packet.

VBScript Syntax[VBScript]

FPCIpPacketFilters.UdpBombDetectionEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_UdpBombDetectionEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_UdpBombDetectionEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether detection of UDP bomb attacks is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCIpPacketFilter object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCIpPacketFilters.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCIpPacketFilters


FPCIpPacketFilters.WinOutOfBandDetectionEnabled Property

Gets or sets whether ISA will detect Windows out-of-band attacks and generate an event. This property only has meaning if FPCIpPacketFilters.Enabled is set to TRUE.

VBScript Syntax[VBScript]

FPCIpPacketFilters.WinOutOfBandDetectionEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_WinOutOfBandDetectionEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_WinOutOfBandDetectionEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether detection of Windows out-of-band attacks is enabled.

The property is read-write.

Applies To

FPCIpPacketFilters


FPCIpRange Object

The FPCIpRange object defines a range of IP addresses defined by a lower bound and an upper bound. The lower and upper bounds are set with the IP_From and IP_To properties. This object is created by setting an IP range for a client address set. Client address sets are ISA policy elements.

The FPCIpRange object is a property of the FPCClientAddressSet object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCIpRange interface.

Methods

The following table lists the methods of the FPCIpRange object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetIps | Sets the bounds of the IP range.

Properties

The following table lists the properties of the FPCIpRange object.

Property | Description
IP_From | Gets the lower bound of the IP range.
IP_To | Gets the upper bound of the IP range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCIpRange.IP_From Property

Gets the lower bound of the IP range.

VBScript Syntax[VBScript]

[ sFrom ] = FPCIpRange.IP_From

C++ Syntax[C++]

HRESULT get_IP_From(
  BSTR *psFrom
);

Parameters

sFrom
String that specifies the lower bound.

The property is read-only.

Applies To

FPCIpRange


FPCIpRange.IP_To Property

Gets the upper bound of the IP range.

VBScript Syntax[VBScript]

[ sTo = ] FPCIpRange.IP_To

C++ Syntax[C++]

HRESULT get_IP_To(
  BSTR *psTo
);

Parameters

sTo
String that specifies the upper bound.

The property is read-only.

Applies To

FPCIpRange


FPCIpRange.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCIpRange.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCIpRange


FPCIpRange.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCIpRange.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCIpRange


FPCIpRange.SetIps Method

Sets the bounds of the IP range.

VBScript Syntax[VBScript]

FPCIpRange.SetIps ( sIp_From, sIp_To )

C++ Syntax[C++]

HRESULT SetIps(
  BSTR sIp_From,
  BSTR sIp_To
);

Parameters

sIp_From
String that specifies the lower bound of the IP range.
sIp_To
String that specifies the upper bound of the IP range.

Applies To

FPCIpRange


FPCLAT Collection

The FPCLAT collection represents the Local Address Table (LAT) of the ISA array. FPCLAT holds a collection of FPCLATEntry objects, each representing one entry in the table. The LAT is a table of all internal IP address ranges used by the internal network behind the ISA server. ISA Server uses the LAT to control the way computers on the internal network communicate with external networks.

The LAT is maintained centrally at the ISA Server computer. Firewall clients automatically download and receive LAT updates at preset intervals. When a Firewall client requests an object, the client checks the LAT. If an IP address request is in the LAT, then the Firewall client requests the object directly. If the IP address request is not in the LAT, the client asks the ISA Server computer to request the object on its behalf.

Secure network address translation (SecureNAT) clients do not have a local copy of the LAT. Therefore, when a SecureNAT client requests an object, the request is sent through ISA Server. If the request is to an external IP address, then ISA Server makes the request on behalf of the client.

This collection is a property of the FPCNetworkConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCLAT interface.

Note When you've made and saved changes to the LAT that will affect whether a Network Interface Card (NIC) is external or internal, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

Methods

The following table lists the methods of the FPCLAT collection.

Method | Description
Add | Creates a new entry in the LAT and returns a reference to it.
AddFromAllCards | Adds to the LAT all the ranges accessible through all network interface cards (NICs) of a specific server, according to the Windows 2000 routing table.
AddFromSelectedAdapters | Adds to the LAT containing all the ranges accessible through the selected network interface cards of a specific server according to the Windows 2000 routing table.
AddPrivateRanges | Adds the private ranges 10.x.x.x, 192.168.x.x. and 172.16.x.x - 172.31.x.x to the LAT.
Clear | Clears the LAT. All entries are removed.
IsIpInternal | Returns a Boolean value that specifies whether an IP address is internal.
Item | Retrieves the given FPCLATEntry object from the collection.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a LAT entry object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCLAT collection.

Property | Description
Count | Gets the number of LAT entries in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCLAT collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLAT.Add Method

Creates a new entry in the Local Address Table (LAT) and returns a reference to it.

Note Changes made by using this method will not take effect until you call the FPCLAT.Save method.

VBScript Syntax[VBScript]

[ oFPCLATEntry = ] FPCLAT.Add( sFrom, sTo )

C++ Syntax[C++]

HRESULT Add(
  BSTR sFrom,
  BSTR sTo,
  IFPCLATEntry **ppoFPCLATEntry
);

Parameters

sFrom
Required. String that specifies the lower IP address of the range.
sTo
Required. String that specifies the higher IP address of the range.

Return Value

oFPCLATEntry
Returns a reference to the new FPCLATEntry object.

Note When you've made and saved changes to the LAT that will affect whether a Network Interface Card (NIC) is external or internal, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

Applies To

FPCLAT


FPCLAT.AddFromAllCards Method

Adds to the LAT all the ranges accessible through all network interface cards (NICs) of a specific server, according to the Windows 2000 routing table.

Note Changes made by using this method will not take effect until you call the FPCLAT.Save method.

VBScript Syntax[VBScript]

FPCLAT.AddFromAllCards( sServerName )

C++ Syntax[C++]

HRESULT AddFromAllCards(
  BSTR sServerName
);

Parameters

sServerName
String that specifies the name of the server whose IP addresses, from all its NICs, should be added to the LAT. If no server is specified, this method will add the IP addresses from the current server to the LAT.

Note When you've made and saved changes to the LAT that will affect whether a Network Interface Card (NIC) is external or internal, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

Applies To

FPCLAT

See Also

AddFromSelectedAdapters


FPCLAT.AddFromSelectedAdapters Method

Adds to the LAT the IP ranges that are accessible through selected network interface cards (NICs). The additional IP ranges are taken from the server specified by the sServerName parameter. The selected NICs are specified by manipulating the Adapters property of the corresponding FPCServer object.

Note Changes made by using this method will not take effect until you call the FPCLAT.Save method.

VBScript Syntax[VBScript]

FPCLAT.AddFromSelectedAdapters( sServerName )

C++ Syntax[C++]

HRESULT AddFromSelectedAdapters(
  BSTR sServerName
);

Parameters

sServerName
String that specifies the name of the server whose IP addresses, from its selected NICs, should be added to the LAT. If no server is specified, the IP addresses from the current server are added to the LAT.

Note When you've made and saved changes to the LAT that will affect whether a Network Interface Card (NIC) is external or internal, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

Applies To

FPCLAT

See Also

AddFromAllCards, FPCServer.Adapters.


FPCLAT.AddPrivateRanges Method

Adds the private ranges 10.x.x.x, 192.168.x.x. and 172.16.x.x - 172.31.x.x to the Local Address Table (LAT).

Note Changes made by using this method will not take effect until you call the FPCLAT.Save method.

VBScript Syntax[VBScript]

FPCLAT.AddPrivateRanges()

C++ Syntax[C++]

HRESULT AddPrivateRanges();

Note When you've made and saved changes to the LAT that will affect whether a Network Interface Card (NIC) is external or internal, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

Applies To

FPCLAT


FPCLAT.Clear Method

Clears the Local Address Table (LAT). All entries are removed.

Note Changes made by using this method will not take effect until you call the FPCLAT.Save method.

VBScript Syntax[VBScript]

FPCLAT.Clear()

C++ Syntax[C++]

HRESULT Clear();

Applies To

FPCLAT


FPCLAT.Count Property

Gets the number of FPCLATEntry objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCLAT.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCLATEntry objects.

The property is read-only.

Applies To

FPCLAT


FPCLAT.IsIpInternal Method

Returns a Boolean value that specifies whether an IP address is internal.

VBScript Syntax[VBScript]

[ bIsInternal = ] FPCLAT.IsIpInternal( sIpStr )

C++ Syntax[C++]

HRESULT IsIpInternal(
  BSTR sIpStr,
  VARIANT_BOOL *pbIsInternal
);

Parameters

sIpStr
String that identifies the IP address.

Return Value

bIsInternal
Boolean value that specifies whether the IP is internal.

Applies To

FPCLAT


FPCLAT.Item Method

Retrieves the given FPCLATEntry object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCLAT.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCLATEntry **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCLATEntry; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCLAT


FPCLAT.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCLAT.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCLAT


FPCLAT.Remove Method

Removes an FPCLATEntry object from the collection.

Note Changes made by using this method will not take effect until you call the FPCLAT.Save method.

VBScript Syntax[VBScript]

FPCLAT.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Note When you've made and saved changes to the LAT that will affect whether a Network Interface Card (NIC) is external or internal, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

Applies To

FPCLAT


FPCLAT.Save Method

Saves the Local Address Table (LAT) information to persistent storage. It is important to remember that changes will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCLAT.Save()

C++ Syntax[C++]

HRESULT Save();

Note When you've made and saved changes to the LAT that will affect whether a Network Interface Card (NIC) is external or internal, the Firewall and Web proxy (w3proxy) services must be restarted for your change to take effect. To stop and restart the services, use the FPCArray.SendRestartNotification method.

Applies To

FPCLAT


FPCLAT.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCLAT collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCLAT.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCLAT


FPCLATEntry Object

Each FPCLATEntry object represents a single entry in the Local Address Table (LAT) of the ISA array. The LAT contains all internal IP address ranges used by the internal network behind the ISA Server computer. ISA Server uses the LAT to determine how computers on the internal network communicate with each other and with external networks.

The LAT is maintained centrally at the ISA Server computer. Firewall clients automatically download and receive LAT updates at preset intervals. When a Firewall client requests an object, the client checks the LAT. If an IP address request is in the LAT, then the Firewall client requests the object directly. If the IP address request is not in the LAT, the client asks the ISA Server computer to request the object on its behalf.

Secure network address translation (SecureNAT) clients do not have a local copy of the LAT. Therefore, when a SecureNAT client requests an object, the request is sent through ISA Server. If the request is to an external IP address, then ISA Server makes the request on behalf of the client.

This object is a part of the FPCLAT collection, which represents the entire table.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCLATEntry interface.

Methods

The following table lists the methods of the FPCLATEntry object.

Method | Description
SetIps | Sets the IP address range of this LAT entry. Sets both the From (start of range) and the To (end of range).

Properties

The following table lists the properties of the FPCLATEntry object.

Property | Description
Description | Gets the description of the LAT entry.
IP_From | Gets the lower IP address of the range.
IP_To | Gets the higher IP address of the range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLATEntry.Description Property

Gets or sets the description of the LAT entry.

VBScript Syntax[VBScript]

FPCLATEntry.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the LAT entry.

The property is read-write.

Applies To

FPCLATEntry


FPCLATEntry.IP_From Property

Gets the lower IP address of the range.

VBScript Syntax[VBScript]

[ sFrom = ] FPCLATEntry.IP_From

C++ Syntax[C++]

HRESULT get_IP_From(
  BSTR *psFrom
);

Parameters

sFrom
String that specifies the lower IP address.

The property is read-only. Set this property by using the SetIps method.

Applies To

FPCLATEntry

See Also

IP_To


FPCLATEntry.IP_To Property

Gets the higher IP address of the range.

VBScript Syntax[VBScript]

[ sTo = ] FPCLATEntry.IP_To

C++ Syntax[C++]

HRESULT get_IP_To(
  BSTR *psTo
);

Parameters

sTo
String that specifies the higher IP address.

The property is read-only. Set this property by using the SetIps method.

Applies To

FPCLATEntry

See Also

IP_From


FPCLATEntry.SetIps Method

Sets the IP address range of this Local Address Table (LAT) entry. Sets both the From IP address (start of range) setting and the To IP address (end of range) setting.

VBScript Syntax[VBScript]

FPCLATEntry.SetFromTo( sNewFrom, sNewTo )

C++ Syntax[C++]

HRESULT SetFromTo(
  BSTR sNewFrom,
  BSTR sNewTo
);

Parameters

sNewFrom
New From IP address.
sNewTo
New To IP address.

Applies To

FPCLATEntry

Applies To

FPCLATEntry


FPCLDT Collection

The FPCLDT collection provides access to all the FPCLDTEntry objects of an ISA Server computer. Through this collection you can add, delete, and modify individual entries of the Local Domain Table (LDT).

Each entry in the table is stored as an individual FPCLDTEntry object.

An LDT lists all the servers in the internal network behind the ISA server. When a client requests an object from a computer and requires name resolution, the client checks the LDT. If the domain name does not appear in the LDT, then the client requests that ISA Server resolve the domain name on its behalf.

After the name resolution server returns the Internet protocol (IP) address of the destination server, the LAT is used to determine whether to go directly to that address or through ISA Server.

Clients use the LDT to determine if a name resolution request should be performed directly or by way of ISA Server. Firewall clients maintain a copy of the LDT, which is updated regularly, on their computer. When a Firewall client attempts to resolve a name, it checks the LDT. If the name is in the LDT, then the Firewall client resolves the name directly. Otherwise, it requests that ISA Server resolve the name by passing the request to a DNS server on the Internet.

The FPCLDT collection is a property of the FPCNetworkConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCLDT interface.

Methods

The following table lists the methods of the FPCLDT collection.

Method | Description
Add | Creates a new LDTEntry object in the list and returns a reference to it.
Item | Retrieves the given LDTEntry object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an LDTEntry object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCLDT collection.

Property | Description
Count | Gets the number of LDTEntry objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data in the LDT collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLDT.Add Method

Creates a new FPCLDTEntry object in the list and returns a reference to it. The Save method must be called to save the added FPCLDTEntry object to persistent storage.

VBScript Syntax[VBScript]

[ oFPCLDTEntry = ] FPCLDT.Add( sDomainName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sDomainName,
  IFPCLDTEntry **ppoFPCLDTEntry
);

Parameters

sDomainName
Required. String that specifies the name of the new LDT entry.

Return Value

oFPCLDTEntry
Returns a reference to an FPCLDTEntry object.

Applies To

FPCLDT


FPCLDT.Count Property

Gets the number of FPCLDTEntry objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCLDT.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCLDTEntry objects.

The property is read-only.

Applies To

FPCLDT


FPCLDT.Item Method

Retrieves the FPCLDTEntry object specified by the index parameter.

VBScript Syntax[VBScript]

[ vItem = ] FPCLDT.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCLDTEntry **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCLDTEntry; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCLDT


FPCLDT.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCLDT.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCLDT


FPCLDT.Remove Method

Removes the FPCLDTEntry object from the collection as specified by the index parameter.

VBScript Syntax[VBScript]

FPCLDT.Remove( vItem )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vItem
);

Parameters

vItem
Required. One-based index or name of the object to remove.

Applies To

FPCLDT


FPCLDT.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCLDT.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCLDT


FPCLDT.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCLDT collection's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCLDT.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCLDT

See Also

FPCLDTEntry


FPCLDTEntry Object

The FPCLDTEntry object represents a single entry in the Local Domain Table (LDT). You can modify individual LDT entries by using this object. An LDT lists all the servers in the internal network behind the ISA server.

When a client requests an object from a computer and requires name resolution, the client checks the LDT. If the domain name does not appear in the LDT, then the client requests that ISA Server resolve the domain name on its behalf.

After the name resolution server returns the Internet protocol (IP) address of the destination server, the LAT is used to determine whether to go directly to that address or through ISA Server.

Clients use the LDT to determine if a name resolution request should be performed directly or via ISA Server. Firewall clients maintain a copy of the LDT, which is updated regularly, on their computer. When a Firewall client attempts to resolve a name, it checks the LDT. If the name is in the LDT, then the Firewall client resolves the name directly. Otherwise, it requests that ISA Server resolve the name by passing the request to a DNS server on the Internet.

This object is a member of the FPCLDT collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCLDTEntry interface.

Methods

The following table lists the methods of the FPCLDTEntry object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCLDTEntry object.

Property | Description
Description | Gets or sets the description.
Name | Gets or sets the name of the domain.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCLDTEntry object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLDTEntry.Description Property

Gets or sets the entry description.

VBScript Syntax[VBScript]

FPCLDTEntry.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the domain.

The property is read-write.

Applies To

FPCLDTEntry


FPCLDTEntry.Name Property

Gets or sets the name of the entry.

VBScript Syntax[VBScript]

FPCLDTEntry.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the domain.

The property is read-write.

Applies To

FPCLDTEntry


FPCLDTEntry.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCLDTEntry.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCLDTEntry


FPCLDTEntry.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCLDTEntry.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCLDTEntry


FPCLDTEntry.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCLDTEntry object's storage. The VendorParametersSets property is designed to allow third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCLDTEntry.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCLDTEntry


FPCListenEntry Object

The FPCListenEntry object defines an IP address on which ISA listens for incoming connections for incoming Web requests or outgoing Web requests. These settings are manipulated with the IP property. The FPCServer.ForwardProxyListenEntries and FPCServer.ReverseProxyListenEntries properties return collections of FPCListenEntry objects.

The FPCListenEntry object is a member of the FPCListenEntries collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCListenEntry interface.

Methods

The following table lists the methods of the FPCListenEntry object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCListenEntry object.

Property | Description
BasicAuthentication | Gets or sets whether basic authentication is used.
Description | Gets or sets the description of the entry.
DigestAuthentication | Gets or sets whether digest authentication is used.
DomainForBasicAuthentication | Gets or sets the domain for basic authentication.
DomainForDigestAuthentication | Gets or sets the domain for digest authentication.
IntegratedWindowsAuthentication | Gets or sets whether integrated Windows authentication is used.
IP | Gets or sets the IP on which the proxy listens.
SSLCertificateAuthentication | Gets or sets whether SSL certificate authentication is used.
SSLServerCertificate | Gets or sets the SSL client certificate used to authenticate the client.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCListenEntry.BasicAuthentication Property

Gets or sets whether basic authentication is used.

The standard Hypertext Transfer Protocol (HTTP) method of authentication is basic authentication. Basic authentication sends and receives user information as text characters that can be easily read. While passwords and user names are encoded, no encryption is used with basic authentication. The following describes the authentication procedure for basic authentication:

  1. The client prompts the user for user name and password credentials.
  2. The credentials are then encoded by the client and sent to the server.
  3. The user name is verified as being an account on the Microsoft Internet Security and Acceleration (ISA) Server computer or in a trusted domain of the ISA Server.

VBScript Syntax[VBScript]

FPCListenEntry.BasicAuthentication [ = bBasicAuthentication ]

C++ Syntax[C++]

HRESULT get_BasicAuthentication(
  VARIANT_BOOL *pbBasicAuthentication
);

HRESULT put_BasicAuthentication(
  VARIANT_BOOL bBasicAuthentication
);

Parameters

bBasicAuthentication
Boolean value that specifies whether basic authentication is used.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.Description Property

Gets or sets the description of the entry.

VBScript Syntax[VBScript]

FPCListenEntry.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the entry.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.DigestAuthentication Property

Gets or sets the whether digest authentication is used.

Digest authentication offers the same features as basic authentication but involves a different way of transmitting the authentication credentials. The authentication credentials pass through a one-way process, often referred to as hashing. The result of this process is called a hash or message digest, and it is not feasible to decrypt it — the original text cannot be deciphered from the hash.

Additional information is added to the password before hashing so that no one can capture the password hash and use it to impersonate the true user. Values are added that help to identify the user, the user's computer, and the domain that the user belongs to. A time stamp is added to prevent a user from using a password after it has been revoked. This is a clear advantage over basic authentication because the password cannot be intercepted and used by an unauthorized person.

VBScript Syntax[VBScript]

FPCListenEntry.DigestAuthentication [ = bDigestAuthentication ]

C++ Syntax[C++]

HRESULT get_DigestAuthentication(
  VARIANT_BOOL *pbDigestAuthentication
);

HRESULT put_DigestAuthentication(
  VARIANT_BOOL bDigestAuthentication
);

Parameters

bDigestAuthentication
Boolean value that specifies whether digest authentication is used.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.DomainForBasicAuthentication Property

Gets or sets the domain for basic authentication.

VBScript Syntax[VBScript]

FPCListenEntry.DomainForBasicAuthentication [ = sDomain ]

C++ Syntax[C++]

HRESULT get_DomainForBasicAuthentication(
  BSTR *psDomain
);

HRESULT put_DomainForBasicAuthentication(
  BSTR sDomain
);

Parameters

sDomain
String value that specifies the name of the domain for basic authentication.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.DomainForDigestAuthentication Property

Gets or sets the domain for digest authentication.

VBScript Syntax[VBScript]

FPCListenEntry.DomainForDigestAuthentication [ = sDomain ]

C++ Syntax[C++]

HRESULT get_DomainForDigestAuthentication(
  BSTR *psDomain
);

HRESULT put_DomainForDigestAuthentication(
  BSTR sDomain
);

Parameters

sDomain
String value that specifies the name of the domain for digest authentication.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.IntegratedWindowsAuthentication Property

Gets or sets whether integrated Windows authentication is used. Integrated Windows authentication is the default authentication for a new listen entry.

Integrated Windows authentication is a secure form of authentication, because the user name and password are not sent across the network. Integrated Windows authentication can use either the Kerberos V5 authentication protocol or its own challenge/response authentication protocol.

Note In a passthrough authentication scenario, ISA Server does not support Kerberos V5 authentication, because Kerberos V5 requires that the client be able to identify the authenticating server.

VBScript Syntax[VBScript]

FPCListenEntry.IntegratedWindowsAuthentication [ = bIntegratedWindowsAuthentication ]

C++ Syntax[C++]

HRESULT get_IntegratedWindowsAuthentication(
  VARIANT_BOOL *pbIntegratedWindowsAuthentication
);

HRESULT put_IntegratedWindowsAuthentication(
  VARIANT_BOOL bIntegratedWindowsAuthentication
);

Parameters

bIntegratedWindowsAuthentication
Boolean value that specifies whether integrated Windows authentication is used.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.IP Property

Gets or sets the IP on which ISA listens.

VBScript Syntax[VBScript]

FPCListenEntry.IP [ = sIp ]

C++ Syntax[C++]

HRESULT get_IP(
  BSTR *psIp
);

HRESULT put_IP(
  BSTR sIp
);

Parameters

sIp
IP string in x.y.z.t format

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCListenEntry.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCListenEntry


FPCListenEntry.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCListenEntry.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCListenEntry


FPCListenEntry.SSLCertificateAuthentication Property

Gets or sets whether SSL certificate authentication is used. For more information, see ISA Server and Secure Sockets Layers.

VBScript Syntax[VBScript]

FPCListenEntry.SSLCertificateAuthentication [ = bSSLCertificateAuthentication ]

C++ Syntax[C++]

HRESULT get_SSLCertificateAuthentication(
  VARIANT_BOOL *pbSSLCertificateAuthentication
);

HRESULT put_SSLCertificateAuthentication(
  VARIANT_BOOL bSSLCertificateAuthentication
);

Parameters

bSSLCertificateAuthentication
Boolean value that specifies whether SSL certificate authentication is used.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntry.SSLServerCertificate Property

Gets or sets the SSL server certificate used to authenticate the ISA Server when a client connects to this FPCListenEntry on the SSL port.

VBScript Syntax[VBScript]

FPCListenEntry.SSLServerCertificate [ = oFPCSSLCertificate ]

C++ Syntax[C++]

HRESULT get_SSLServerCertificate (
  IFPCSSLCertificate *poFPCSSLCertificate
);

HRESULT put_SSLServerCertificate (
  IFPCSSLCertificate oFPCSSLCertificate
);

Parameters

oFPCSSLCertificate
Reference to an FPCSSLCertificate object.

The property is read-write.

Applies To

FPCListenEntry


FPCListenEntries Collection

The FPCListenEntries collection provides access to a group of FPCListenEntry objects. Each FPCListenEntry object defines an IP address on which ISA listens for incoming connections for incoming Web requests or outgoing Web requests. These settings are manipulated by means of the IP property of each FPCListenEntry object.

This object is a property of the FPCWebProxy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCListenEntries interface.

Note When you've made and saved changes to the port numbers that the Web proxy (w3proxy) service listens on, the Web proxy service must be restarted for your change to take effect. To stop and restart the Web proxy service use the FPCArray.SendRestartNotification method.

Methods

The following table lists the methods of the FPCListenEntries collection.

Method | Description
Add | Adds a new FPCListenEntry object.
Item | Retrieves the given FPCListenEntry object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an item from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCListenEntries collection.

Property | Description
AllBasicAuthentication | Gets or sets whether basic authentication is used.
AllDigestAuthentication | Gets or sets whether digest authentication is used.
AllDomainForBasicAuthentication | Gets or sets a string value that specifies the domain for basic authentication.
AllDomainForDigestAuthentication | Gets or sets a string value that specifies the domain for digest authentication.
AllIntegratedWindowsAuthentication | Gets or sets whether integrated Windows authentication is used.
AllSSLCertificateAuthentication | Gets or sets SSL certificate authentication is used.
AllSSLServerCertificate | Gets or sets an FPCSSLCertificate object that represents the client certificate to use when authenticating the client.
Count | Gets the number of entries in the collection.
Description | Gets or sets the description of the collection of listen entries.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCListenEntries collection' storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCListenEntries.Add Method

Adds a new FPCListenEntry object to the collection. If there are no listen entries configured, then ISA does not listen for incoming or outgoing Web requests.

VBScript Syntax[VBScript]

[ oFPCListenEntry = ] FPCListenEntries.Add( sIP )

C++ Syntax[C++]

HRESULT Add(
  BSTR sIP,
  IFPCListenEntry **ppoFPCListenEntry
);

Parameters

sIP
String that specifies the IP address to listen on.

Return Value

oFPCListenEntry
Reference to the FPCListenEntry object.

Applies To

FPCListenEntries


FPCListenEntries.AllBasicAuthentication Property

Gets or sets whether basic authentication is used.

The standard Hypertext Transfer Protocol (HTTP) method of authentication is basic authentication. Basic authentication sends and receives user information as text characters that can be easily read. While passwords and user names are encoded, no encryption is used with basic authentication. The following describes the authentication procedure for basic authentication:

  1. The client prompts the user for user name and password credentials.
  2. The credentials are then encoded by the client and sent to the server.
  3. The user name is verified as being an account on the Microsoft Internet Security and Acceleration (ISA) Server computer or in a trusted domain of the ISA Server.

VBScript Syntax[VBScript]

FPCListenEntries.AllBasicAuthentication [ = bAllBasicAuthentication ]

C++ Syntax[C++]

HRESULT get_AllBasicAuthentication(
  VARIANT_BOOL *pbAllBasicAuthentication
);

HRESULT put_AllBasicAuthentication(
  VARIANT_BOOL bAllBasicAuthentication
);

Parameters

bAllBasicAuthentication
Boolean that specifies whether basic authentication is used.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllDigestAuthentication Property

Gets or sets whether digest authentication is used.

Digest authentication offers the same features as basic authentication but involves a different way of transmitting the authentication credentials. The authentication credentials pass through a one-way process, often referred to as hashing. The result of this process is called a hash or message digest, and it is not feasible to decrypt it — the original text cannot be deciphered from the hash.

Additional information is added to the password before hashing so that no one can capture the password hash and use it to impersonate the true user. Values are added that help to identify the user, the user's computer, and the domain that the user belongs to. A time stamp is added to prevent a user from using a password after it has been revoked. This is a clear advantage over basic authentication because the password cannot be intercepted and used by an unauthorized person.

VBScript Syntax[VBScript]

FPCListenEntries.AllDigestAuthentication [ = bAllDigestAuthentication ]

C++ Syntax[C++]

HRESULT get_AllDigestAuthentication(
  VARIANT_BOOL *pbAllDigestAuthentication
);

HRESULT put_AllDigestAuthentication(
  VARIANT_BOOL bAllDigestAuthentication
);

Parameters

bAllDigestAuthentication
Boolean that specifies whether digest authentication is used.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllDomainForBasicAuthentication Property

Gets or sets a string value that specifies the domain for basic authentication.

VBScript Syntax[VBScript]

FPCListenEntries.AllDomainForBasicAuthentication [ = sDomain ]

C++ Syntax[C++]

HRESULT get_AllDomainForBasicAuthentication(
  BSTR *psDomain
);

HRESULT put_AllDomainForBasicAuthentication(
  BSTR sDomain
);

Parameters

sDomain
String that specifies the domain for basic authentication.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllDomainForDigestAuthentication Property

Gets or sets a string value that specifies the domain for digest authentication.

VBScript Syntax[VBScript]

FPCListenEntries.AllDomainForDigestAuthentication [ = sDomain ]

C++ Syntax[C++]

HRESULT get_AllDomainForDigestAuthentication(
  BSTR *psDomain
);

HRESULT put_AllDomainForDigestAuthentication(
  BSTR sDomain
);

Parameters

sDomain
String that specifies the domain for digest authentication.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllIntegratedWindowsAuthentication Property

Gets or sets whether integrated Windows authentication is used. Integrated Windows authentication is the default authentication for a new listen entry.

Integrated Windows authentication is a secure form of authentication, because the user name and password are not sent across the network. Integrated Windows authentication can use either the Kerberos V5 authentication protocol or its own challenge/response authentication protocol.

Note In a passthrough authentication scenario, ISA Server does not support Kerberos V5 authentication, because Kerberos V5 requires that the client be able to identify the authenticating server.

VBScript Syntax[VBScript]

FPCListenEntries.AllIntegratedWindowsAuthentication [ = bAllIntegratedWindowsAuthentication ]

C++ Syntax[C++]

HRESULT get_AllIntegratedWindowsAuthentication(
  VARIANT_BOOL *pbAllIntegratedWindowsAuthentication
);

HRESULT put_AllIntegratedWindowsAuthentication(
  VARIANT_BOOL bAllIntegratedWindowsAuthentication
);

Parameters

bAllIntegratedWindowsAuthentication
Boolean that specifies whether integrated Windows authentication is used.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllSSLCertificateAuthentication Property

Gets or sets whether SSL certificate authentication is used. For more information, see ISA Server and Secure Sockets Layers.

VBScript Syntax[VBScript]

FPCListenEntries.AllSSLCertificateAuthentication [ = bAllSSLCertificateAuthentication ]

C++ Syntax[C++]

HRESULT get_AllSSLCertificateAuthentication(
  VARIANT_BOOL *pbAllSSLCertificateAuthentication
);

HRESULT put_AllSSLCertificateAuthentication(
  VARIANT_BOOL bAllSSLCertificateAuthentication
);

Parameters

bAllSSLCertificateAuthentication
Boolean that specifies whether SSL certificate authentication is used.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.AllSSLServerCertificate Property

Gets or sets an FPCSSLCertificate object that represents the server certificate to use for authenticating against the client when SSL certificate authentication is enabled.

VBScript Syntax[VBScript]

FPCListenEntries.AllSSLServerCertificate [ = oFPCSSLCertificate ]

C++ Syntax[C++]

HRESULT get_AllSSLServerCertificate (
  IFPCSSLCertificate *poFPCSSLCertificate
);

HRESULT put_AllSSLServerCertificate (
  IFPCSSLCertificate oFPCSSLCertificate
);

Parameters

oFPCSSLCertificate
Reference to an FPCSSLCertificate object.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.Count Property

Gets the number of FPCListenEntry objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCListenEntries.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of listen entry objects.

The property is read-only.

Applies To

FPCListenEntries


FPCListenEntries.Description Property

Gets or sets the description of the collection of listen entries.

VBScript Syntax[VBScript]

FPCListenEntries.Descriptions [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the collection of listen entries.

The property is read-write.

Applies To

FPCListenEntries


FPCListenEntries.Item Method

Retrieves the given FPCListenEntry object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCListenEntries.Item( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  IFPCListenEntry **pvItem
);

Parameters

lIndex
Required. One-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCListenEntry; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCListenEntries


FPCListenEntries.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCListenEntries.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCListenEntries


FPCListenEntries.Remove Method

Removes an FPCListenEntry object from the collection.

VBScript Syntax[VBScript]

FPCListenEntries.Remove( lIndex )

C++ Syntax[C++]

HRESULT Remove(
  long lIndex
);

Parameters

lIndex
Required. One-based index of the object to remove.

Applies To

FPCListenEntries


FPCListenEntries.Save Method

Saves all FPCListenEntry objects in the collection to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCListenEntries.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCListenEntries


FPCListenEntries.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCListenEntries collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCListenEntries.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCListenEntries

See Also

FPCListenEntry


FPCLog Object

The FPCLog object is used to set the logging configuration of a specific component. There are three possible logging components:

  • Web proxy
  • Firewall service
  • Packet filtering

FPCLog is a member of the FPCLogs collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCLog interface.

Methods

The following table lists the methods of the FPCLog object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCLog object.

Property | Description
ComponentType | Gets the type of the component to which this configuration belongs.
Enabled | Gets or sets a Boolean value that specifies whether logging is enabled.
LogDbDataSource | Gets or sets the name of the structured query language (SQL) data source.
LogDbPassword | Sets the password for the SQL table.
LogDbTableName | Gets or sets the name of the SQL table.
LogDbUserName | Gets or sets the user name of the SQL table.
LogFieldSelection | Gets or sets a bit field selection of logged columns.
LogFileDirectory | Gets or sets the directory containing the text log files.
LogFileDirectoryType | Gets or sets the type of path to the logging files.
LogFileKeepOld | Gets or sets an integer value that specifies the number of old log files to keep.
LogFilePeriod | Gets or sets the period of time before starting a new text log file.
LogFilesCompress | Gets or sets a Boolean value that specifies whether text log files are compressed.
LogType | Gets or sets the log type.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLog.ComponentType Property

Gets the type of component to which this log configuration belongs. There are three possible logging components:

  • Web proxy
  • Firewall service
  • Packet filtering

VBScript Syntax[VBScript]

[ LoggingComponents = ] FPCLog.ComponentType

C++ Syntax[C++]

HRESULT get_ComponentType(
  FpcLoggingComponents *pLoggingComponents
);

Parameters

LoggingComponents
A value from the FpcLoggingComponents enumerated type.
The property is read-only.

Applies To

FPCLog


FPCLog.Enabled Property

Gets or sets whether logging is enabled.

VBScript Syntax[VBScript]

FPCLog.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether logging is enabled.

The property is read-write.

Applies To

FPCLog


FPCLog.LogDbDataSource Property

Gets or sets the SQL database source name (DSN).

VBScript Syntax[VBScript]

FPCLog.LogDbDataSource [ = sDSN ]

C++ Syntax[C++]

HRESULT get_LogDBDataSource(
  BSTR *psDSN
);

HRESULT put_LogDBDataSource(
  BSTR sDSN
);

Parameters

sDSN
String that specifies the SQL DSN.

The property is read-write.

Applies To

FPCLog


FPCLog.LogDbPassword Property

Sets the password for the SQL table.

VBScript Syntax[VBScript]

FPCLog.LogDbPassword [ = sPassword ]

C++ Syntax[C++]

HRESULT put_LogDbPassword(
  BSTR sPassword
);

Parameters

sPassword
String that specifies the password.

The property is write-only.

Applies To

FPCLog


FPCLog.LogDbTableName Property

Gets or sets the name of the SQL table.

VBScript Syntax[VBScript]

FPCLog.LogDbTableName [ = sTableName ]

C++ Syntax[C++]

HRESULT get_LogDbTableName(
  BSTR *psTableName
);

HRESULT put_LogDbTableName(
  BSTR sTableName
);

Parameters

sTableName
String that specifies the SQL table name.

The property is read-write.

Applies To

FPCLog


FPCLog.LogDbUserName Property

Gets or sets the user name of the SQL table.

VBScript Syntax[VBScript]

FPCLog.LogDbUserName [ = sUserName ]

C++ Syntax[C++]

HRESULT get_LogDbUserName(
  BSTR *psUserName
);

HRESULT put_LogDbUserName(
  BSTR sUserName
);

Parameters

sUserName
String that specifies the SQL table user name.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFieldSelection Property

Gets or sets a bit field selection of logged columns. The first bit (0) refers to the first column of a log object, the second bit to the second column, and so on. Tables of fields that can be included in ISA log files are provided in Log Fields.

VBScript Syntax[VBScript]

FPCLog.LogFieldSelection[ = iSelection ]

C++ Syntax[C++]

HRESULT get_LogFieldSelection(
  int *piSelection
);

HRESULT put_LogFieldSelection(
  int iSelection
);

Parameters

iSelection
Bit field that specifies the logged columns.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFileDirectory Property

Gets or sets the directory that contains the text log files.

Note This property is used only if LogFileDirectoryType is set to fpcFullPath. Otherwise the files are logged to the directory ISALogs in the ISA installation directory.

VBScript Syntax[VBScript]

FPCLog.LogFileDirectory [ = sDirectory ]

C++ Syntax[C++]

HRESULT get_LogFileDirectory(
  BSTR *psDirectory
);

HRESULT put_LogFileDirectory(
  BSTR sDirectory
);

Parameters

sDirectory
String that specifies the directory.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFileDirectoryType Property

Gets or sets the type of path to the logging files.

VBScript Syntax[VBScript]

FPCLog.LogFileDirectoryType [ = DirectoryType ]

C++ Syntax[C++]

HRESULT get_LogFileDirectoryType(
  FpcLogFileDirectoryType *pDirectoryType
);

HRESULT put_LogFileDirectoryType(
  FpcLogFileDirectoryType DirectoryType
);

Parameters

DirectoryType
Value from the FpcLogFileDirectoryType enumerated type, either fpcFullPath, indicating that the directory of the log files is given as a full path, or fpcRelativePath, indicating that the directory of the log files is relative to the ISA installation directory.

If the value fpcLogRelativePath is selected, the LogFileDirectoryType property is ignored.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFileKeepOld Property

Gets or sets an integer value that specifies the number of old log files to keep.

Note Setting the value to 0 disables this property.

VBScript Syntax[VBScript]

FPCLog.LogFileKeepOld [ = iKeepOld ]

C++ Syntax[C++]

HRESULT get_LogFileKeepOld(
  int *piKeepOld
);

HRESULT put_LogFileKeepOld(
  int iKeepOld
);

Parameters

iKeepOld
Number of old files that are retained.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFilePeriod Property

Gets or sets the period of time before starting a new log text file.

VBScript Syntax[VBScript]

FPCLog.LogFilePeriod [ = Period ]

C++ Syntax[C++]

HRESULT get_LogFilePeriod(
  FpcLogPeriod *pPeriod
);

HRESULT put_LogFilePeriod(
  FpcLogPeriod Period
);

Parameters

Period
Value from the FpcLogPeriod enumerated type.

The property is read-write.

Applies To

FPCLog


FPCLog.LogFilesCompress Property

Gets or sets a Boolean value that specifies whether text log files are compressed.

Note This feature is supported only when logging to partitions formatted using NTFS file systems.

VBScript Syntax[VBScript]

FPCLog.LogFilesCompress [ = bCompress ]

C++ Syntax[C++]

HRESULT get_LogFilesCompress(
  VARIANT_BOOL *pbCompress
);

HRESULT put_LogFilesCompress(
  VARIANT_BOOL bCompress
);

Parameters

bCompress
A Boolean value that specifies whether text log files are compressed.

The property is read-write.

Applies To

FPCLog


FPCLog.LogType Property

Gets or sets the type of the log. This can be ISA File Format, W3C Extended Log File Format, or ODBC database.

VBScript Syntax[VBScript]

FPCLog.LogType [ = Type ]

C++ Syntax[C++]

HRESULT get_LogType(
  FpcLogType *pType
);

HRESULT put_LogType(
  FpcLogType Type
);

Parameters

Type
A value from the FpcLogType enumerated type.

The property is read-write.

Applies To

FPCLog


FPCLog.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCLog.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCLog


FPCLog.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCLog.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCLog


FPCLogs Collection

The FPCLogs collection is used to access the collection of FPCLog objects.

FPCLogs is a property of an FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCLogs interface.

Methods

The following table lists the methods of the FPCLogs collection.

Method | Description
Item | Retrieves the given FPCLog object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the collection's configuration to persistent storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCLogs.Item Method

Retrieves the given FPCLog object from the collection. This can be the Web proxy log, the Firewall service log, or the packet filters log.

VBScript Syntax[VBScript]

[ vItem = ] FPCLogs.Item( LoggingComponents )

C++ Syntax[C++]

HRESULT Item(
  FpcLoggingComponents LoggingComponents,
  IFPCLog **pvItem
);

Parameters

LoggingComponents
A value from the FpcLoggingComponents enumerated type.

Return Values

vItem
If successful, returns the FPCLog object specified by the LoggingComponents parameter; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCLogs


FPCLogs.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCLogs.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCLogs


FPCLogs.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCLogs.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCLogs


FPCNetworkConfiguration Object

The FPCNetworkConfiguration object is used to access the network configuration.

This object is a property of the FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCNetworkConfiguration interface.

Methods

The following table lists the methods of the FPCNetworkConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCNetworkConfiguration object.

Property | Description
FirewallChaining | Gets an object that defines Firewall service chaining.
LAT | Gets a reference to an object for accessing the Local Address Table (LAT) configuration.
LDT | Gets a reference to an object for accessing the Local Domain Table (LDT) configuration.
RoutingRules | Gets a collection of all routing rules.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCNetworkConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCNetworkConfiguration.FirewallChaining Property

Gets an object that defines Firewall service chaining. See FPCFirewallChaining for more information.

VBScript Syntax[VBScript]

[ oFPCFirewallChaining = ] FPCNetworkConfiguration.FirewallChaining

C++ Syntax[C++]

HRESULT get_FirewallChaining(
  IFPCFirewallChaining **poFPCFirewallChaining
);

Parameters

oFPCFirewallChaining
Reference to the FPCFirewallChaining object.

The property is read-only.

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.LAT Property

Gets a reference to an object for accessing the Local Address Table (LAT) configuration.The LAT is a table of all internal IP address ranges used by the internal network behind the ISA Server. ISA Server uses the LAT to control the way computers on the internal network communicate with external networks.

VBScript Syntax[VBScript]

[ collFPCLAT = ] FPCNetworkConfiguration.LAT

C++ Syntax[C++]

HRESULT get_LAT(
  IFPCLAT **pcollFPCLAT
);

Parameters

collFPCLAT
Reference to the FPCLAT collection.

The property is read-only.

Example

The following Visual Basic Scripting Edition code adds a new LAT entry to the FPCLAT collection.

Set objFPC  = CreateObject ("FPC.Root")
Set objNetConfig = objFPC.Arrays(1).NetworkConfiguration
Set objLAT = objNetConfig.LAT
ObjLAT.Add "2.2.2.2","3.3.3.3"
ObjLAT.Save

Applies To

FPCNetworkConfiguration

See Also

FPCLATEntry


FPCNetworkConfiguration.LDT Property

Gets a reference to an object for accessing the Local Domain Table (LDT) configuration. The LDT lists each computer, with a dot in its name, that is located in the internal network behind the ISA server.

VBScript Syntax[VBScript]

[ collFPCLDT = ] FPCNetworkConfiguration.LDT

C++ Syntax[C++]

HRESULT get_LDT(
  IFPCLDT **pcollFPCLDT
);

Parameters

collFPCLDT
Reference to the FPCLDT collection.

The property is read-only.

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCNetworkConfiguration.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.RoutingRules Property

Gets a collection of all routing rules. For more information see FPCRoutingRules.

VBScript Syntax[VBScript]

[ collFPCRoutingRules = ] FPCNetworkConfiguration.RoutingRules

C++ Syntax[C++]

HRESULT get_RoutingRules(
  IFPCRoutingRules **pcollFPCRoutingRules
);

Parameters

collFPCRoutingRules
Reference to the FPCRoutingRules collection.

Applies To

FPCNetworkConfiguration

See Also

FPCRoutingRule


FPCNetworkConfiguration.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCNetworkConfiguration.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCNetworkConfiguration


FPCNetworkConfiguration.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the object's storage. This property allows third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCNetworkConfiguration.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCNetworkConfiguration


FPCPolicyElements Object

The FPCPolicyElements object is used to access configuration settings of ISA, including schedules, bandwidth priorities, destination sets, client address sets, and protocol definitions. The properties of the FPCPolicyElements object are closely mirrored by what is shown under the Policy Elements node of ISA Management. Configuration settings of each of these categories are programmatically managed through the FPCPolicyElements object.

This object is a property of the FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCPolicyElements interface.

Methods

The following table lists the methods of the FPCPolicyElements object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCPolicyElements object.

Property | Description
BandwidthPriorities | Gets the collection of bandwidth priorities in this array.
ClientAddressSets | Gets a collection of all client address sets in this array.
ContentGroups | Gets a collection of all content groups in this array.
DestinationSets | Gets a collection of all destination sets in this array.
DialupEntries | Gets a collection of dialup entries.
EventDefinitions | Gets a collection of all alert events in this array.
ProtocolDefinitions | Gets a collection for accessing the Firewall service protocols.
Schedules | Gets a collection of all schedules in this array.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCPolicyElements object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPolicyElements.BandwidthPriorities Property

Gets the collection of bandwidth priorities in this array. Bandwidth priorities can be added and removed with the Add and Remove methods of the FPCBandwidthPriorities collection. Bandwidth priorities are used by the rules to define bandwidth resource allocation among competing requests.

VBScript Syntax[VBScript]

[ collFPCBandwidthPriorities = ] FPCPolicyElements.BandwidthPriorities

C++ Syntax[C++]

HRESULT get_BandwidthPriorities(
  IFPCBandwidthPriorities **pcollFPCBandwidthPriorities
);

Parameters

collFPCBandwidthPriorities
Reference to the FPCBandwidthPriorities collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.ClientAddressSets Property

Gets a collection of all client address sets in this array. Client address sets can be added and removed with the Add and Remove methods of the FPCClientAddressSets collection. A client address set is a set of client IP addresses used by a rule.

VBScript Syntax[VBScript]

[ collFPCClientAddressSets = ] FPCPolicyElements.ClientAddressSets

C++ Syntax[C++]

HRESULT get_ClientAddressSets(
  IFPCClientAddressSets **pcollFPCClientAddressSets
);

Parameters

collFPCClientAddressSets
Reference to an FPCClientAddressSets collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.ContentGroups Property

Gets a collection of all content groups in this array. The returned FPCContentGroups collection of FPCContentGroup objects can be used to programmatically update content groups.

The FPCContentGroup object describes and provides access to content-type groups The default content-type groups include Audio, Executable, Images, Text, and Video. Each group includes file types. For example, the Audio content group could include the file types .aif, .aifc, .au, .m3u, .mid, and others.

VBScript Syntax[VBScript]

[ collFPCContentGroups = ] FPCPolicyElements.ContentGroups

C++ Syntax[C++]

HRESULT get_ContentGroups(
  IFPCContentGroups **pcollFPCContentGroups
);

Parameters

collFPCContentGroups
Reference to an FPCContentGroups collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.DestinationSets Property

Gets a collection of all destination sets in this array. A destination set is a group of destinations that the Web proxy can access. You can use the FPCDestinationSets collectioncollection that is returned to programmatically update destination sets. Automating the task of updating destination sets can save time for a system administrator by using ISA. For an example of a script to perform this task, see Configuring Destination Sets.

VBScript Syntax[VBScript]

[ collFPCDestinationSets = ] FPCPolicyElements.DestinationSets

C++ Syntax[C++]

HRESULT get_DestinationSets(
  IFPCDestinationSets **pcollFPCDestinationSets
);

Parameters

collFPCDestinationSets
Reference to the FPCDestinationSets collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.DialupEntries Property

Gets a collection of all dialup entries in this array. You can use the FPCDialUpEntries collection that is returned to update dialup entries programmatically.

VBScript Syntax[VBScript]

[ collFPCDialupEntries = ] FPCPolicyElements.DialupEntries

C++ Syntax[C++]

HRESULT get_DialupEntries(
  IFPCDialupEntries **pcollFPCDialupEntries
);

Parameters

collFPCDialupEntries
Reference to the FPCDialUpEntries collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.EventDefinitions Property

Gets a reference to a FPCEventDefinitions collection. An FPCEventDefinition object is used to define a single event. Events describe conditions that require the attention of an administrator, and predetermined actions can be taken in response to particular events by using the FPCAlert object.

Events can be added and removed with the Add and Remove methods of the collection.

VBScript Syntax[VBScript]

[ collFPCEventDefinitions = ] FPCPolicyElements.EventDefinitions

C++ Syntax[C++]

HRESULT get_EventDefinitions(
  IFPCEventDefinitions **pcollFPCEventDefinitions
);

Parameters

collFPCEventDefinitions
Reference to an FPCEventDefinitions collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.ProtocolDefinitions Property

Gets a reference to an FPCProtocolDefinitions collection. This collection is used to access the Firewall service protocols. Only user-defined Firewall service protocols can be added and removed with the Add and Remove methods of the FPCProtocolDefinitions collection. Predefined protocols are read-only.

VBScript Syntax[VBScript]

[ collFPCProtocolDefinitions = ] FPCPolicyElements.ProtocolDefinitions

C++ Syntax[C++]

HRESULT get_ProtocolDefinitions(
  IFPCProtocolDefinitions **pcollFPCProtocolDefinitions
);

Parameters

collFPCProtocolDefinitions
Reference to an FPCProtocolDefinitions collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCPolicyElements.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCPolicyElements


FPCPolicyElements.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCPolicyElements.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCPolicyElements


FPCPolicyElements.Schedules Property

Gets a collection of all schedules in this array. ISA schedules are defined by hour blocks defined within each day of the week, and are accessed by means of the FPCSchedules collection.

For an example of using the FPCSchedules collection, see Configuring Schedules.

VBScript Syntax[VBScript]

[ collFPCSchedules = ] FPCPolicyElements.Schedules

C++ Syntax[C++]

HRESULT get_Schedules(
  IFPCSchedules **pcollFPCSchedules
);

Parameters

collFPCSchedules
Reference to an FPCSchedules collection.

This property is read-only.

Applies To

FPCPolicyElements


FPCPolicyElements.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCPolicyElements object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCPolicyElements.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to an FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCPolicyElements


FPCPrimaryRoute Object

The FPCPrimaryRoute object represents the primary route entity, either a single ISA server or an array of ISA servers. This object is a property of the FPCRoutingRule object, which you can access through the FPCRoutingRule.PrimaryRoute property.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCPrimaryRoute interface.

Methods

The following table lists the methods of the FPCPrimaryRoute object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetAutoPollConfig | Sets whether polling of the upstream server or array for membership information is enabled.
SetRedirectHostAndPorts | Sets whether requests are redirected to a hosted site, specified by a host site name and port number.
SetServerAndPort | Sets the server and port for the primary route server or array.

Properties

The following table lists the properties of the FPCPrimaryRoute object.

Property | Description
AuthenticationEnabled | Gets or sets whether use of authentication in upstream routing is enabled.
AuthenticationType | Gets or sets the type of authentication that the primary route server or array uses.
AutoDialOut | Gets a reference to an FPCAutoDial object that represents the automatic-dial settings.
AutomaticPollConfig | Gets whether proxy polling of the upstream proxy or array for membership information is enabled.
BackupRoute | Gets a reference to an object that represents the specific proxy or array of the secondary (backup) route.
Credentials | Gets an FPCCredentials object used to read and write credentials information. This information is used if a proxy server needs to authenticate with an upstream proxy server.
PollAtUrl | Gets the URL, usually at the upstream proxy, at which to poll for the array configuration information. This property if valid if the AutomaticPollConfig property is enabled.
RedirectHost | Gets the host name for the redirect host site.
RedirectHostPort | Gets the port number for the redirection to the host site.
RedirectHostSSLPort | Gets the port number for the redirection to the host site by using SSL.
RouteServerName | Gets the name of the server or array to which the request should be redirected.
RouteServerPort | Gets the port that this primary route server or array is listening on.
RouteServerSSLPort | Gets the port for listening on a secure channel.
RouteType | Gets or sets the primary route type.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPrimaryRoute.AuthenticationEnabled Property

Gets or sets whether use of authentication in upstream routing is enabled. Authentication should not be enabled unless a valid FPCCredentials object can be retrieved by the FPCPrimaryRoute.Credentials property.

VBScript Syntax[VBScript]

FPCPrimaryRoute.AuthenticationEnabled [= bEnabled ]

C++ Syntax[C++]

HRESULT get_AuthenticationEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_AuthenticationEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether authentication is enabled.

The property is read-write.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.AuthenticationType Property

Gets or sets the type of authentication that the primary route server or array uses if authentication is enabled.

VBScript Syntax[VBScript]

FPCPrimaryRoute.AuthenticationType [ = AuthType ]

C++ Syntax[C++]

HRESULT get_AuthenticationType(
  FpcAuthType *pAuthType
);

HRESULT put_AuthenticationType(
  FpcAuthType AuthType
);

Parameters

AuthType
Authentication type. It can have a value from the FpcAuthType enumerated type.

The property is read-write.

Remarks

Basic authentication (fpcUiAuthBasic) is not encrypted.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.AutoDialOut Property

Gets a reference to an FPCAutoDial object that represents the automatic-dial settings.

VBScript Syntax[VBScript]

[ oFPCAutoDial = ] FPCPrimaryRoute.AutoDialOut

C++ Syntax[C++]

HRESULT get_AutoDialOut(
  IFPCAutoDial **poFPCAutoDial
);

Parameters

oFPCAutoDial
Reference to an FPCAutoDial object that represents the automatic-dial settings.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.AutomaticPollConfig Property

Gets whether polling of the upstream proxy or array for membership information is enabled .

VBScript Syntax[VBScript]

FPCPrimaryRoute.AutomaticPollConfig [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_AutomaticPollConfig(
  VARIANT_BOOL *pbEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether proxy polling is enabled.

The property is read-only. It can be modified through the SetAutoPollConfig method.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.BackupRoute Property

Gets a reference to an object that represents the specific server or array of the backup route.

VBScript Syntax[VBScript]

[ oFPCBackupRoute = ] FPCPrimaryRoute.BackupRoute

C++ Syntax[C++]

HRESULT get_BackupRoute(
  IFPCBackupRoute **poFPCBackupRoute
);

Parameters

oFPCBackupRoute
Reference to the FPCBackupRoute object.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.Credentials Property

Gets an FPCCredentials object that is used to read and write credential information. An ISA Server computer will use this information if it needs to authenticate a connection to an upstream proxy server.

VBScript Syntax[VBScript]

[ oFPCCredentials = ] FPCPrimaryRoute.Credentials

C++ Syntax[C++]

HRESULT get_Credentials(
  IFPCCredentials **poFPCCredentials
);

Parameters

oFPCCredentials
Reference to an FPCCredentials object.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.PollAtUrl Property

Gets the URL that points to an upstream server, to poll for the upstream server's array configuration information. This property is valid if the AutomaticPollConfig property is enabled.

VBScript Syntax[VBScript]

[ sURL = ] FPCPrimaryRoute.PollAtURL

C++ Syntax[C++]

HRESULT get_PollAtURL(
  BSTR *psURL
);

Parameters

sURL
String that specifies the URL.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RedirectHost Property

Gets the name for the redirect site.

VBScript Syntax[VBScript]

[ sHost = ] FPCPrimaryRoute.RedirectHost

C++ Syntax[C++]

HRESULT get_RedirectHost(
  long *psHost
);

Parameters

sHost
String that specifies the host.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RedirectHostPort Property

Gets the port number for the redirection.

VBScript Syntax[VBScript]

[ lPort = ] FPCPrimaryRoute.RedirectHostPort

C++ Syntax[C++]

HRESULT get_RedirectHostPort(
  long *plPort
);

Parameters

lPort
Long value that specifies the port.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RedirectHostSSLPort Property

Gets the port number for a redirection by using SSL.

VBScript Syntax[VBScript]

[ lSSLPort = ] FPCPrimaryRoute.RedirectHostSSLPort

C++ Syntax[C++]

HRESULT get_RedirectHostSSLPort(
  long *plSSLPort
);

Parameters

lSSLPort
Long value that specifies the port.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCPrimaryRoute.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteServerName Property

Gets the name of the server or array to which the request should be redirected.

VBScript Syntax[VBScript]

[ sName = ] FPCPrimaryRoute.RouteServerName

C++ Syntax[C++]

HRESULT get_RouteServerName(
  BSTR *psName
);

Parameters

sName
String that specifies the name of the server or array.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteServerPort Property

Gets the port on which this primary route server or array is listening.

VBScript Syntax[VBScript]

[ lPort = ] FPCPrimaryRoute.RouteServerPort

C++ Syntax[C++]

HRESULT get_RouteServerPort(
  long *plPort
);

Parameters

lPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-only.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteServerSSLPort Property

Gets the port for listening on a secure channel.

VBScript Syntax[VBScript]

[ lSSLPort = ] FPCPrimaryRoute.RouteServerSSLPort

C++ Syntax[C++]

HRESULT get_RouteServerSSLPort(
  long *plSSLPort
);

Parameters

lSSLPort
Long value that specifies the port number. It can be a value from 1 to 65535.

The property is read-only

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.RouteType Property

Gets or sets the primary route type, either to the requested destination, to an upstream ISA Server or array, or to an alternate site.

VBScript Syntax[VBScript]

FPCPrimaryRoute.RouteType [ = RouteType ]

C++ Syntax[C++]

HRESULT get_RouteType(
  FpcPrimaryRouteType *pRouteType
);

HRESULT put_RouteType(
  FpcPrimaryRouteType RouteType
);

Parameters

RouteType
Routing type. It can have a value from the FpcPrimaryRouteType enumerated type.

The property is read-write.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCPrimaryRoute.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.SetAutoPollConfig Method

Sets whether the upstream server or array should be polled for array membership.

VBScript Syntax[VBScript]

FPCPrimaryRoute.SetAutoPollConfig(fSetAuto, sAutoPollUrl )

C++ Syntax[C++]

HRESULT SetAutoPollConfig(
  VARIANT_BOOL fSetAuto,
  BSTR sAutoPollUrl
);

Parameters

fSetAuto
A Boolean expression that specifies whether automatic configuration is to be enabled.
sAutoPollUrl
An optional string that specifies the URL, usually at the upstream server, to poll for the array configuration information. If fSetAuto is set to TRUE, this parameter must hold a valid URL; otherwise, sAutoPollUrl is ignored.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.SetRedirectHostAndPorts Method

Sets whether requests are redirected to a hosted site, specified by a host site name and port number.

VBScript Syntax[VBScript]

FPCPrimaryRoute.SetRedirectHostAndPorts [= sHost , lRedirectHostPort, lRedirectHostSSLPort ]

C++ Syntax[C++]

HRESULT SetRedirectHostAndPorts (
  BSTR sHost,
  long lRedirectHostPort
  long lRedirectHostSSLPort
);

Parameters

sHost
String that specifies the Host.
lRedirectHostPort
Long value that specifies the host port number.
lRedirectHostSSLPort
Long value that specifies the host port number for SSL.

Applies To

FPCPrimaryRoute


FPCPrimaryRoute.SetServerAndPort Method

Sets the server and port for the primary route server or array.

VBScript Syntax[VBScript]

FPCPrimaryRoute.SetServerAndPort( sServerName, lPort, lSSLPort )

C++ Syntax[C++]

HRESULT SetServerAndPort(
  BSTR sServerName,
  long lPort
  long lSSLPort
);

Parameters

sServerName
String that specifies the name of the server.
lPort
Long value that specifies the port number that the server listens on. It can be a value from 1 to 65535.
lSSLPort
Long value that specifies the port number that the server listens on for SSL requests. It can be a value from 1 to 65535.

Applies To

FPCPrimaryRoute


FPCProtocolConnection Object

The FPCProtocolConnection object represents a single connection in a single Firewall service protocol. This object is a member of the FPCProtocolConnections collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCProtocolConnection interface.

Methods

The following table lists the methods of the FPCProtocolConnection object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetTCP | Sets all of the parameters of a TCP connection.
SetUDP | Sets all of the parameters of a UDP connection.

Properties

The following table lists the properties of the FPCProtocolConnection object.

Property | Description
PortHigh | Gets a port number designating the end of the range.
PortLow | Gets a port number designating the beginning of the range.
Protocol | Gets the communication protocol of the connection.
TCPDirection | Gets the direction of a TCP connection.
UDPDirection | Gets the direction of a UDP connection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCProtocolConnection object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolConnection.PortHigh Property

Gets a port number designating the high end of the range.

VBScript Syntax[VBScript]

[ lPort = ] FPCProtocolConnection.PortHigh

C++ Syntax[C++]

HRESULT get_PortHigh(
  long *plPort
);

Parameters

lPort
Long value that specifies the high end of the portrange. It can be a value from 1 through 65535.

The property is read-only.

Remarks

This value can be equal to the PortLow property to indicate that there is only one port, not a range of ports.

Applies To

FPCProtocolConnection


FPCProtocolConnection.PortLow Property

Gets a port number designating the low end of the range.

VBScript Syntax[VBScript]

[ lPort = ] FPCProtocolConnection.PortLow

C++ Syntax[C++]

HRESULT get_PortLow(
  long *plPort
);

Parameters

lPort
Long value that specifies the beginning port number. It can be a value from 1 through 65535.

The property is read-only.

Applies To

FPCProtocolConnection


FPCProtocolConnection.Protocol Property

Gets the communication protocol of the connection. The protocol can be either TCP or UDP.

VBScript Syntax[VBScript]

[ ConnectionProtocolType = ] FPCProtocolConnection.Protocol

C++ Syntax[C++]

HRESULT get_Protocol(
  FpcConnectionProtocolType *pConnectionProtocolType
);

Parameters

ConnectionProtocolType
Communication protocol used in the connection. It can have a value of the FpcConnectionProtocolType enumerated type.

The property is read-only.

Applies To

FPCProtocolConnection


FPCProtocolConnection.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCProtocolConnection.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCProtocolConnection


FPCProtocolConnection.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCProtocolConnection.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCProtocolConnection


FPCProtocolConnection.SetTCP Method

Sets all of the parameters of a TCP connection.

VBScript Syntax[VBScript]

FPCProtocolConnection.SetTCP(lPortLo, lPortHi, Direction)

C++ Syntax[C++]

HRESULT SetTCP(
  long lPortLo,
  long lPortHi,
  FpcConnectionDirectionType Direction
);

Parameters

lPortLo
Long value that specifies the beginning port number. It can be a value from 1 through 65535.
lPortHi
Long value that specifies the ending port number. It can be a value from 1 through 65535, and must be equal to or greater than the value of the iPortLo parameter.
Direction
Required. Connection direction. It can have a value from the FpcConnectionDirectionType enumerated type.

Applies To

FPCProtocolConnection


FPCProtocolConnection.SetUDP Method

Sets all of the parameters of a UDP connection.

VBScript Syntax[VBScript]

FPCProtocolConnection.SetUDP(lPortLo, lPortHi, Direction)

C++ Syntax[C++]

HRESULT SetUDP(
  long lPortLo,
  long lPortHi,
  FpcUDPConnectionDirectionType Direction
);

Parameters

lPortLo
Long value that specifies the beginning port number. It can be a value from 1 through 65535.
lPortHi
Long value that specifies the ending port number. It can be a value from 1 through 65535 and must be equal to or greater than the value of the iPortLo parameter.
Direction
Required. Connection direction. It can have a value from the FpcUDPConnectionDirectionType enumerated type.

Applies To

FPCProtocolConnection


FPCProtocolConnection.TCPDirection Property

Gets the direction of a TCP connection.

VBScript Syntax[VBScript]

[ TCPDirection = ] FPCProtocolConnection.TCPDirection

C++ Syntax[C++]

HRESULT get_TCPDirection(
  FpcConnectionDirectionType *pTCPDirection
);

Parameters

TCPDirection
Specifies the TCP connection direction, and can have a value from the FpcConnectionDirectionType enumerated type.

The property is read-only. Set the direction by using the SetTCP Method.

Applies To

FPCProtocolConnection


FPCProtocolConnection.UDPDirection Property

Gets the direction of the UDP connection.

VBScript Syntax[VBScript]

[ UDPDirection = ] FPCProtocolConnection.UDPDirection

C++ Syntax[C++]

HRESULT get_UDPDirection(
  FpcConnectionDirectionType *pUDPDirection
);

Parameters

UDPDirection
Specifies the UDP connection direction, and can have a value from the FpcUDPConnectionDirectionType enumerated type.

The property is read-only. Set the direction by using the SetUDP Method.

Applies To

FPCProtocolConnection


FPCProtocolConnection.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCProtocolConnection object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCProtocolConnection.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolConnection


FPCProtocolConnections Collection

The FPCProtocolConnections collection retrieves a group of all FPCProtocolConnection objects of a single protocol.

The FPCProtocolConnections collection is a property of the FPCProtocolDefinition object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCProtocolConnections interface.

Methods

The following table lists the methods of the FPCProtocolConnections collection.

Method | Description
AddTCP | Creates a new TCP connection object and returns a reference to it.
AddUDP | Creates a new UDP connection object and returns a reference to it.
Item | Retrieves the given FPCProtocolConnection object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes the given object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCProtocolConnections collection.

Property | Description
Count | Gets the number of secondary connection objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCProtocolConnections collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolConnections.AddTCP Method

Creates a new TCP connection object and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCProtocolConnection = ] FPCProtocolConnections.AddTCP( Direction, lPortLow, lPortHigh )

C++ Syntax[C++]

HRESULT AddTCP(
  FpcConnectionDirectionType Direction,
  long lPortLow,
  long lPortHigh,
 IFPCProtocolConnection **poFPCProtocolConnection
);

Parameters

Direction
Required. Connection direction. It can have a value from the FpcConnectionDirectionType enumerated type.
lPortLow
Lower bound of the port range used in the connection.
lPortHigh
Higher bound of the port range used in the connection.

Return Value

oFPCProtocolConnection
Returns a reference to the new FPCProtocolConnection object if successful; NULL otherwise.

Applies To

FPCProtocolConnections


FPCProtocolConnections.AddUDP Method

Creates a new UDP connection object and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCProtocolConnection = ] FPCProtocolConnections.AddUDP( Direction, lPortLow, lPortHigh )

C++ Syntax[C++]

HRESULT AddUDP(
  FpcUDPConnectionDirectionType Direction,
  long lPortLow,
  long lPortHigh,
 IFPCProtocolConnection **poFPCProtocolConnection
);

Parameters

Direction
Required. Connection direction. It can have a value from the FpcUDPConnectionDirectionType enumerated type.
lPortLow
Lower bound of the port range used in the connection.
lPortHigh
Higher bound of the port range used in the connection.

Return Value

oFPCProtocolConnection
Returns a reference to the new FPCProtocolConnection object if successful; NULL otherwise.

Applies To

FPCProtocolConnections


FPCProtocolConnections.Count Property

Gets the number of secondary connection objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCProtocolConnections.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of secondary connection objects.

The property is read-only.

Applies To

FPCProtocolConnections


FPCProtocolConnections.Item Method

Retrieves the given FPCProtocolConnection object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCProtocolConnections.Item( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  IFPCProtocolConnection **pvItem
);

Parameters

lIndex
Required. Number that specifies the one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCProtocolConnection; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCProtocolConnections


FPCProtocolConnections.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCProtocolConnections.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCProtocolConnections


FPCProtocolConnections.Remove Method

Removes the given object from the collection.

VBScript Syntax[VBScript]

FPCProtocolConnections.Remove( lIndex )

C++ Syntax[C++]

HRESULT Remove(
  long lIndex
);

Parameters

lIndex
Required. One-based index of the object to remove.

Applies To

FPCProtocolConnections

See Also

FPCProtocolConnection


FPCProtocolConnections.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCProtocolConnections.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCProtocolConnections


FPCProtocolConnections.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCProtocolConnections collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCProtocolConnections.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolConnections


FPCProtocolDefinition Object

The FPCProtocolDefinition object represents a single Firewall service protocol, supported by the Firewall service. This object represents predefined protocols that come with ISA Server, and user-defined protocols. Application filter protocols are represented by the FPCFilterProtocols collection.

Protocol definitions are used in server publishing, in protocol rules, and in bandwidth rules.

The FPCProtocolDefinition object is a member of the FPCProtocolDefinitions collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCProtocolDefinition interface.

Methods

The following table lists the methods of the FPCProtocolDefinition object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCProtocolDefinition object.

Property | Description
Description | Gets or sets the description of the protocol.
InitialConnectionPort | Gets the port of the initial (primary) connection.
InitialConnectionProtocol | Gets the protocol of the initial (primary) connection.
IsISAProtocol | Gets a Boolean value that specifies whether the protocol is an ISA protocol.
Name | Gets or sets the name of the protocol.
SecondaryConnections | Gets a collection of all of this protocol's secondary connections.
TCPInitialConnectionDirection | Gets the direction of the initial (primary) TCP connection.
UDPInitialConnectionDirection | Gets the direction of the initial (primary) UDP connection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCProtocolDefinition object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolDefinition.Description Property

Gets or sets the description of the protocol.

VBScript Syntax[VBScript]

FPCProtocolDefinition.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the protocol.

The property is read-write.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.InitialConnectionPort Property

Gets the port of the initial (primary) connection.

VBScript Syntax[VBScript]

[ lPort = ] FPCProtocolDefinition.InitialConnectionPort

C++ Syntax[C++]

HRESULT get_InitialConnectionPort(
  long *plPort
);

Parameters

lPort
Long value that specifies the port. Can be a value from 1 through 65535.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.InitialConnectionProtocol Property

Gets the protocol of the initial (primary) connection.

VBScript Syntax[VBScript]

[ Protocol = ] FPCProtocolDefinition.InitialConnectionProtocol

C++ Syntax[C++]

HRESULT get_InitialConnectionProtocol(
  FpcConnectionProtocolType *pProtocol
);

Parameters

Protocol
Protocol used in the connection. It can have a value from the FpcConnectionProtocolType enumerated type.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.IsISAProtocol Property

ISA Server comes with predefined protocol definitions, which you can use when you create protocol rules. The IsISAProtocol property gets a Boolean value that specifies whether the protocol is a predefined ISA protocol, as opposed to a user-defined protocol.

VBScript Syntax[VBScript]

[ bProtocol = ] FPCProtocolDefinition.IsISAProtocol

C++ Syntax[C++]

HRESULT get_IsISAProtocol(
  VARIANT_BOOL *pbProtocol
);

Parameters

bProtocol
Boolean value that specifies whether the protocol is a predefined ISA protocol.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.Name Property

Gets or sets the name of the protocol.

VBScript Syntax[VBScript]

FPCProtocolDefinition.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the protocol.

The property is read-write.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCProtocolDefinition.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCProtocolDefinition.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.SecondaryConnections Property

Gets a collection of all of this protocol's secondary connections.

VBScript Syntax[VBScript]

[ collFPCProtocolConnections = ] FPCProtocolDefinition.SecondaryConnections

C++ Syntax[C++]

HRESULT get_SecondaryConnections(
  IFPCProtocolConnections **pcollFPCProtocolConnections
);

Parameters

collFPCProtocolConnections
Reference to the FPCProtocolConnections collection.

The property is read-only.

Applies To

FPCProtocolDefinition

See Also

FPCProtocolConnection


FPCProtocolDefinition.TCPInitialConnectionDirection Property

Gets the direction of the initial (primary) TCP connection.

VBScript Syntax[VBScript]

[ Direction = ] FPCProtocolDefinition.TCPInitialConnectionDirection

C++ Syntax[C++]

HRESULT get_TCPInitialConnectionDirection(
  FpcConnectionDirectionType *pDirection
);

Parameters

Direction
Value that specifies the connection direction. It can have a value from the FpcConnectionDirectionType enumerated type.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.UDPInitialConnectionDirection Property

Gets the direction of the initial (primary) UDP connection.

VBScript Syntax[VBScript]

[ Direction = ] FPCProtocolDefinition.UDPInitialConnectionDirection

C++ Syntax[C++]

HRESULT get_UDPInitialConnectionDirection(
  FpcConnectionDirectionType *pDirection
);

Parameters

Direction
Value that specifies the connection direction. It can have a value from the FpcUDPConnectionDirectionType enumerated type.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinition.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCProtocolDefinition object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCProtocolDefinition.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolDefinition


FPCProtocolDefinitions Collection

The FPCProtocolDefinitions collection provides access to all the Firewall service protocols in an ISA array. It gives access to the collection of FPCProtocolDefinition objects.

This collection is a property of the FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCProtocolDefinitions interface.

Methods

The following table lists the methods of the FPCProtocolDefinitions collection.

Method | Description
AddTCP | Creates a new TCP protocol object and returns a reference to it.
AddUDP | Creates a new UDP protocol object and returns a reference to it.
Item | Retrieves the given FPCProtocolDefinition object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes the given object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCProtocolDefinitions collection.

Property | Description
Count | Gets the number of protocol objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCProtocolDefinitions collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolDefinitions.AddTCP Method

Creates a new TCP protocol definition object and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCProtocolDefinition = ] FPCProtocolDefinitions.AddTCP( sName, InitialConnectionDirection, lInitialConnectionPort )

C++ Syntax[C++]

HRESULT AddTCP(
  BSTR sName,
  FpcConnectionDirectionType InitialConnectionDirection,
  long lInitialConnectionPort,
  IFPCProtocolDefinition **poFPCProtocolDefinition
);

Parameters

sName
Required. String that specifies the name of the new protocol object.
InitialConnectionDirection
The direction of the initial connection associated with the protocol. Can have a value from the FpcConnectionDirectionType enumerated type.
lInitialConnectionPort
Long value specifying the port for the initial connection associated with the protocol. Can be any value between 1 and 65535.

Return Value

oFPCProtocolDefinition
Returns a reference to an FPCProtocolDefinition object.

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.AddUDP Method

Creates a new UDP protocol definition object and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCProtocolDefinition = ] FPCProtocolDefinitions.AddUDP( sName, InitialConnectionDirection, InitialConnectionPort )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  FpcUDPConnectionDirectionType InitialConnectionDirection,
  long lInitialConnectionPort,
  IFPCProtocolDefinition **poFPCProtocolDefinition
);

Parameters

sName
Required. String that specifies the name of the new protocol object.
InitialConnectionDirection
The direction of the initial connection associated with the protocol. Can have a value from the FpcUDPConnectionDirectionType enumerated type.
lInitialConnectionPort
Long value specifying the port for the initial connection associated with the protocol. Can be any value between 1 and 65535.

Return Value

oFPCProtocolDefinition
Returns a reference to an FPCProtocolDefinition object.

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.Count Property

Gets the number of protocol objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCProtocolDefinitions.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of protocol objects.

The property is read-only.

Applies To

FPCProtocolDefinitions

See Also

FPCProtocolDefinition


FPCProtocolDefinitions.Item Method

Retrieves the given FPCProtocolDefinition object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCProtocolDefinitions.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCProtocolDefinition **pvItem
);

Parameters

vIndex
Required. Number that specifies the one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCProtocolDefinition; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCProtocolDefinitions.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.Remove Method

Removes the given object from the collection.

VBScript Syntax[VBScript]

FPCProtocolDefinitions.Remove( vIndex, bVerify )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
  VARIANT_BOOL bVerify
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.
bVerify
Optional. Boolean value that specifies whether COM verifies, prior to removal, if the protocol definition is used by a rule. The default value is TRUE.

Applies To

FPCProtocolDefinitions

See Also

FPCProtocolDefinition


FPCProtocolDefinitions.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCProtocolDefinitions.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCProtocolDefinitions


FPCProtocolDefinitions.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCProtocolDefinitions collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCProtocolDefinitions.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolDefinitions


FPCProtocolRule Object

The FPCProtocolRule object represents a single ISA protocol rule. A protocol rule defines a set of protocols that are permitted or denied for certain users or IP addresses at certain times. These times are defined by a schedule.

A protocol rule can apply to one of the following:

  • A specified set of protocols.
  • All IP traffic. This includes all connection combinations, even those that are not designated as a protocol within the protocols collection.

For example, you could use this object to create a rule that allows the FTP protocol but only during nonbusiness hours. To define a schedule of nonbusiness hours, use the FPCSchedule object.

This object is a member of the FPCProtocolRules collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCProtocolRule interface.

Methods

The following table lists the methods of the FPCProtocolRule object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetAppliesAlways | Sets the rule to apply always.
SetSchedule | Sets the schedule to which the rule applies.

Properties

The following table lists the properties of the FPCProtocolRule object.

Property | Description
Action | Gets or sets whether the rule allows or denies use of protocols.
AppliesAlways | Gets whether the rule applies at all times.
AppliesToAccounts | Gets the collection of accounts to which the rule applies.
AppliesToMethod | Gets or sets the method used for deciding rule applicability.
ClientAddressSetsExcluded | Gets the collection of client address sets to which the rule does not apply.
ClientAddressSetsUsed | Gets the collection of client address sets to which the rule applies.
Description | Gets or sets the description of the rule.
Enabled | Gets or sets whether the rule is enabled.
Name | Gets or sets the name of the protocol rule.
ProtocolSelectionMethod | Gets or sets whether the rule applies to all IP traffic, all IP traffic exclusive of certain protocols, or to specified protocols.
ScheduleUsed | Gets the name of the FPCRef object that is used to define the times when the rule applies.
SpecifiedProtocols | Gets the FPCRefs collection of protocols for which the rule applies.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCProtocolRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolRule.Action Property

Gets or sets whether the rule allows or denies use of protocols.

VBScript Syntax[VBScript]

FPCProtocolRule.Action [ = ProtocolRuleAction ]

C++ Syntax[C++]

HRESULT get_Action(
  FpcProtocolRuleAction *pProtocolRuleAction
);

HRESULT put_Action(
  FpcProtocolRuleAction ProtocolRuleAction
);

Parameters

ProtocolRuleAction
Defines whether the rule allows or denies protocols. It can have a value from the FpcProtocolRuleAction enumerated type.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.AppliesAlways Property

Gets whether the rule applies at all times.

VBScript Syntax[VBScript]

[ bApplies = ]ProtocolRule.AppliesAlways

C++ Syntax[C++]

HRESULT get_AppliesAlways(
  VARIANT_BOOL *pbApplies
);

Parameters

bApplies
Boolean value that specifies whether a rule always applies.

The property is read-only. It can be set to VARIANT_TRUE by calling the SetAppliesAlways method. It is set to VARIANT_FALSE if you call the SetSchedule method. When this property is set to VARIANT_FALSE, the schedule defined by the ScheduleUsed property will define the times at which the rule applies.

Applies To

FPCProtocolRule


FPCProtocolRule.AppliesToAccounts Property

Gets the collection of accounts.

The account status, included or excluded, is set when you add the account to the collection by using the FPCAccounts.Add method.

VBScript Syntax[VBScript]

[ collFPCAccounts = ] FPCProtocolRule.AppliesToAccounts

C++ Syntax[C++]

HRESULT get_AppliesToAccounts(
  IFPCAccounts **pcollFPCAccounts
);

Parameters

collFPCAccounts
Reference to the FPCAccounts collection.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRule.AppliesToMethod Property

Gets or sets the whether the rule applies to all requests, requests from specific users, or requests from specific computers.

VBScript Syntax[VBScript]

FPCProtocolRule.AppliesToMethod [ = AppliesToType ]

C++ Syntax[C++]

HRESULT get_AppliesToMethod(
  FpcAppliesToType *pAppliesToType
);

HRESULT put_AppliesToMethod(
  FpcAppliesToType AppliesToType
);

Parameters

AppliesToType
Value from the FpcAppliesToType enumerated type that indicates to what type of request the rule will apply.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.ClientAddressSetsExcluded Property

Gets the collection of client address sets to which the rule does not apply. This property is useful only when the ClientSetsUsed property is not empty. It allows you to design a rule that applies to one set of clients but excludes another set of clients.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCProtocolRule.ClientAddressSetsExcluded

C++ Syntax[C++]

HRESULT get_ClientAddressSetsExcluded(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
Reference to an FPCRefs collection that contains references to the client address sets that are excluded.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRule.ClientAddressSetsUsed Property

Gets the collection of client address sets to which the rule applies.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCProtocolRule.ClientAddressSetsUsed

C++ Syntax[C++]

HRESULT get_ClientAddressSetsUsed(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
Reference to an FPCRefs collection that contains references to the client address sets that are used.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRule.Description Property

Gets or sets the description of the rule.

VBScript Syntax[VBScript]

FPCProtocolRule.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.Enabled Property

Gets or sets whether the rule is enabled.

VBScript Syntax[VBScript]

FPCProtocolRule.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the rule is enabled.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.Name Property

Gets or sets the name of the protocol rule.

VBScript Syntax[VBScript]

FPCProtocolRule.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the protocol rule's name.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.ProtocolSelectionMethod Property

Gets or sets whether the rule applies to all IP traffic, all IP traffic exclusive of certain protocols, or to specified protocols.

VBScript Syntax[VBScript]

FPCProtocolRule.ProtocolSelectionMethod [ = ProtocolSelectionType ]

C++ Syntax[C++]

HRESULT get_ProtocolSelectionMethod(
  FpcProtocolSelectionType *pProtocolSelectionType
);

HRESULT put_ProtocolSelectionMethod(
  FpcProtocolSelectionType ProtocolSelectionType
);

Parameters

ProtocolSelectionType
Value from the FpcProtocolSelectiontype enumerated type.

The property is read-write.

Applies To

FPCProtocolRule


FPCProtocolRule.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCProtocolRule.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCProtocolRule


FPCProtocolRule.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCProtocolRule.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCProtocolRule


FPCProtocolRule.ScheduleUsed Property

Gets FPCRef object that contains a reference to the schedule used to define the times when the rule applies.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCProtocolRule.ScheduleUsed

C++ Syntax[C++]

HRESULT get_ScheduleUsed(
  IFPCRef **poFPCRef
);

Parameters

oFPCRef
The FPCRef object that contains a reference to the schedule.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRule.SetAppliesAlways Method

Sets the rule to always apply. When the SetAppliesAlways method is enabled, the ScheduleUsed property becomes meaningless.

VBScript Syntax[VBScript]

FPCProtocolRule.SetAppliesAlways()

C++ Syntax[C++]

HRESULT SetAppliesAlways();

Applies To

FPCProtocolRule


FPCProtocolRule.SetSchedule Method

Sets the schedule to which the rule applies. This method also sets the AppliesAlways property to FALSE.

VBScript Syntax[VBScript]

FPCProtocolRule.SetSchedule( sScheduleName, ItemScope )

C++ Syntax[C++]

HRESULT SetSchedule(
  BSTR sScheduleName,
  FpcItemScope ItemScope
);

Parameters

sScheduleName
String specifying the name of the schedule to which the rule applies.
ItemScope
Item scope. It can have a value from the FpcItemScope enumerated type. Has a default value of fpcArrayScope.

Applies To

FPCProtocolRule


FPCProtocolRule.SpecifiedProtocols Property

Gets an FPCRefs collection of FPCRef objects that point to the protocols to which the rule applies.

VBScript Syntax[VBScript]

[ collFPCRefs = ]FPCProtocolRule.SpecifiedProtocols

C++ Syntax[C++]

HRESULT get_SpecifiedProtocols(
  IFPCRefs **pcollFPCRefs
);

Return values

collFPCRefs
Reference to an FPCRefs collection.

Example

The following Visual Basic code illustrates the use of the SpecifiedProtocols property.

  Dim objFPC As New FPCLib.FPC
  Dim MyProtocolRules As FPCProtocolRules
  Dim myarray As FPCArray
  Set myarray = objFPC.Arrays.GetContainingArray
  Dim rule As FPCProtocolRule

  Set MyProtocolRules = myarray.ArrayPolicy.ProtocolRules
  Set rule = MyProtocolRules.Add("Web access")
  rule.Action = fpcActionAllow
  rule.Description = "Basic web access to everyone"
  rule.Enabled = True
  rule.ProtocolSelectionMethod = fpcSpecifiedProtocols
  rule.SpecifiedProtocols.Add ("HTTP")
  rule.SpecifiedProtocols.Add ("HTTP-S")
  rule.SetAppliesAlways
  MyProtocolRules.Save

Applies To

FPCProtocolRule


FPCProtocolRule.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCProtocolRule object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCProtocolRule.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolRule


FPCProtocolRules Collection

The FPCProtocolRules collection provides access to a group of FPCProtocolRule objects. This collection is a property of the FPCEnterprisePolicy object and the FPCArrayPolicy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCProtocolRules interface.

Methods

The following table lists the methods of the FPCProtocolRules collection.

Method | Description
Add | Creates a new rule, adds it to the collection, and returns a reference to it.
Item | Retrieves the given FPCProtocolRule object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a protocol rule object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCProtocolRules collection.

Property | Description
Count | Gets the number of rule objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCProtocolRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCProtocolRules.Add Method

Creates a new rule, adds it to the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCProtocolRule = ] FPCProtocolRules.Add( sRuleName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sRuleName,
  IFPCProtocolRule **ppoFPCProtocolRule
);

Parameters

sRuleName
Required. String that specifies the name of the rule.

Return Value

oFPCProtocolRule
Reference to the FPCProtocolRule object.

Applies To

FPCProtocolRules


FPCProtocolRules.Count Property

Gets the number of rule objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCProtocolRules.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of rule objects.

The property is read-only.

Applies To

FPCProtocolRules

See Also

FPCProtocolRule


FPCProtocolRules.Item Method

Retrieves the given FPCProtocolRule object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCProtocolRules.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCProtocolRule **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCProtocolRule; otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCProtocolRules


FPCProtocolRules.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCProtocolRules.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCProtocolRules


FPCProtocolRules.Remove Method

Removes a protocol rule object from the collection.

VBScript Syntax[VBScript]

FPCProtocolRules.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCProtocolRules

See Also

FPCProtocolRule


FPCProtocolRules.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCProtocolRules.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCProtocolRules


FPCProtocolRules.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCProtocolRules collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCProtocolRules.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCProtocolRules


FPCPublishing Object

The FPCPublishing object represents a container for two sub-objects that represent the two publishing features of ISA Server and their associated rules:

  • Server publishing processes incoming requests to internal servers, such as Simple Mail Transfer Protocol (SMTP) servers, File Transfer Protocol (FTP) servers, Structured Query Language (SQL) servers, and others. Requests are forwarded downstream to an internal server, located behind the ISA Server computer. Server publishing rules determine how server publishing functions, essentially filtering all incoming and outgoing requests through the ISA Server computer.
  • Web publishing processes incoming requests for Hypertext Transfer Protocol (HTTP) objects on an internal Web server. Web publishing rules determine how ISA Server should intercept incoming requests for HTTP objects and whether ISA Server should respond on behalf of the Web server. Requests are forwarded downstream to an internal Web server, located behind the ISA Server computer.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCPublishing interface.

Methods

The following table lists the methods of the FPCPublishing object.

Method | Description
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCPublishing object.

Property | Description
ServerPublishingRules | Gets the FPCServerPublishingRules collection of FPCServerPublishingRule objects used for other protocols publishing.
VendorParametersSets | Gets a reference to an object used to access a vendor's data.
WebPublishingRules | Gets a collection of all Web publishing rules.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCPublishing.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call are lost.

VBScript Syntax[VBScript]

FPCPublishing.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCPublishing


FPCPublishing.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs will not be saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCPublishing.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCPublishing


FPCPublishing.ServerPublishingRules Property

Gets the collection of server publishing rules.

Server publishing processes incoming requests to internal servers, such as Simple Mail Transfer Protocol (SMTP) servers, File Transfer Protocol (FTP) servers, Structured Query Language (SQL) servers, and others. Requests are forwarded downstream to an internal server, located behind the ISA Server computer. Server publishing rules determine how server publishing functions, essentially filtering all incoming and outgoing requests through the ISA Server computer.

VBScript Syntax[VBScript]

[ collFPCServerPublishingRules = ] FPCPublishing.ServerPublishingRules

C++ Syntax[C++]

HRESULT get_ServerPublishingRules(
  IFPCServerPublishingRules **pcollFPCServerPublishingRules
);

Parameters

collFPCServerPublishingRules
Reference to the FPCServerPublishingRules collection.

The property is read-only.

Applies To

FPCPublishing


FPCPublishing.VendorParametersSets Property

Gets a reference to an object used to access a vendor's data.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCPublishing.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCPublishing


FPCPublishing.WebPublishingRules Property

Gets a collection of all Web publishing rules.

Web publishing processes incoming requests for Hypertext Transfer Protocol (HTTP) objects on an internal Web server. Web publishing rules determine how ISA Server should intercept incoming requests for HTTP objects and whether ISA Server should respond on behalf of the Web server. Requests are forwarded downstream to an internal Web server, located behind the ISA Server computer.

VBScript Syntax[VBScript]

[ collFPCWebPublishingRules = ] FPCPublishing.WebPublishingRules

C++ Syntax[C++]

HRESULT get_WebPublishingRules(
  IFPCWebPublishingRules **pcollFPCWebPublishingRules
);

Parameters

collFPCWebPublishingRules
Reference to the FPCWebPublishingRules collection.

This property is read-only.

Applies To

FPCPublishing


FPCRef Object

The FPCRef object is used to reference another object. You can use the FPCRef object and the FPCRefs collection to retrieve values needed for specific scripting situations. Here are several lines of Microsoft® Visual Basic® Scripting Edition code demonstrating use of FPCRef and FPCRefs:

'Using the FPCRefs.Add method to add an FPCRef object reference to
'a client address set to the list of excluded address sets
objarr.ArrayPolicy.SiteAndContentRules (1).ClientAddressSetsExcluded.Add "ClientSet_1"
'Using the FPCRef.Name property to retrieve the name of an excluded
'client address set
objarr.ArrayPolicy.SiteAndContentRules (1).ClientAddressSetsExcluded(1).Name

A full example using FPCRefs is provided in Creating and Applying Enterprise Policy to an Array. FPCRefs is also used in Preventing Access in a Web Publishing Scenario.

This object is a member of the FPCRefs collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCRef interface.

Methods

The following table lists the methods of the FPCRef object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCRef object.

Property | Description
ApplicationFilterGuid | Gets the GUID that identifies the application filter. The vendor of the application filter provides the GUID. For a nonapplication filter protocol this value would be an empty string.
Name | Gets the name of object referenced by the object.
Scope | Gets a value from the FpcItemScope enumerated type that specifies the scope of this object.
VendorParametersSets | Not implemented for this object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRef.ApplicationFilterGuid Property

Gets the globally unique identifier (GUID) that identifies the application filter. The vendor of the application filter provides the GUID. For a nonapplication filter protocol this value would be an empty string. This property only applies to FPCRef objects that point to application filters, not to FPCRef objects that point to other references, such as schedules or destinations.

VBScript Syntax[VBScript]

[ sGuid = ] FPCRef.ApplicationFilterGuid

C++ Syntax[C++]

HRESULT get_ApplicationFilterGuid(
  BSTR *psGuid
);

Parameters

sGuid
String that specifies the GUID that identifies the application filter.

The property is read-only.

Applies To

FPCRef


FPCRef.Name Property

Gets the name of the object referenced by the FPCRef object.

VBScript Syntax[VBScript]

[ sName = ] FPCRef.Name

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

Parameters

sName
String that specifies the name.

The property is read-only.

Applies To

FPCRef


FPCRef.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCRef.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCRef


FPCRef.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCRef.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCRef


FPCRef.Scope Property

Gets a value from the FpcItemScope enumerated type that specifies the scope of this object.

VBScript Syntax[VBScript]

[ ItemScope = ] FPCRef.Scope

C++ Syntax[C++]

HRESULT get_Scope(
  FpcItemScope *pItemScope
);

Parameters

ItemScope
Item scope. It can have a value of fpcArrayScope or fpcEnterpriseScope from the FpcItemScope enumerated type. The value will be fpcArrayScope for a standard edition server or stand-alone server.

The property is read-only.

Applies To

FPCRef


FPCRefs Collection

The FPCRefs collection represents a group of objects that are used by a rule. FPCRefs can contain references to client address sets, protocols, or content groups. Note that each instance of FPCRefs will contain a homogenous set of FPCRef objects.

The FPCRef object is used to reference another object. You can use the FPCRef object and the FPCRefs collection to retrieve values needed for specific scripting situations. Here are several lines of VBScript code demonstrating use of FPCRef and FPCRefs:

'Using the FPCRefs.Add method to add an FPCRef object reference to
'a client address set to the list of excluded address sets
objarr.ArrayPolicy.SiteAndContentRules (1).ClientAddressSetsExcluded.Add "ClientSet_1"
'Using the FPCRef.Name property to retrieve the name of an excluded
'client address set
objarr.ArrayPolicy.SiteAndContentRules (1).ClientAddressSetsExcluded(1).Name

A full example using FPCRefs is provided in Creating and Applying Enterprise Policy to an Array. FPCRefs is also used in Preventing Access in a Web Publishing Scenario.

The FPCRefs collection is a property of the FPCSiteAndContentRule, FPCWebPublishingRule, FPCBandwidthRule, and FPCProtocolRule objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCRefs interface.

Methods

The following table lists the methods of the FPCRefs collection.

Method | Description
Add | Adds a new FPCRef object to the collection.
Exists | Returns TRUE if an object having the specified properties currently exists in the collection.
Item | Retrieves the given FPCRef object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCRef object from the collection.
RemoveAll | Removes all entries from the collection.
RemoveSpecified | Removes an object identified by its properties.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCRefs collection.

Property | Description
Count | Gets the number of items collection.
VendorParametersSets | Not implemented for this object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRefs.Add Method

Adds a new FPCRef object to the collection.

Usage examples for this method are shown in Preventing Access in a Web Publishing Scenario and Creating and Applying Enterprise Policy to an Array.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCRefs.Add( sName, sApplicationFilterGuid, ItemScope )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  BSTR sApplicationFilterGuid,
  FpcItemScope ItemScope,
  IFPCRef **ppoFPCRef
);

Parameters

sName
Required. String that specifies the name of the object to be added.
sApplicationFilterGuid
Optional. String that specifies the GUID of the application filter if the object being added represents an application filter protocol.
ItemScope
Item scope. It can have a value from the FpcItemScope enumerated type. Has a default value of fpcArrayScope. Must have a value of fpcArrayScope for a standard edition server or stand-alone server.

Return Values

oFPCRef
Returns a reference to the new FPCRef object.

Applies To

FPCRefs


FPCRefs.Count Property

Gets the number of items in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCRefs.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of protocols.

The property is read-only.

Applies To

FPCRefs


FPCRefs.Exists Method

Returns TRUE if an object that has the specified properties exists in the collection.

VBScript Syntax[VBScript]

[ bExists = ] FPCRefs.Exists ( sName, sApplicationFilterGuid, Scope )

C++ Syntax[C++]

HRESULT Exists(
  BSTR sName,
  BSTR sApplicationFilterGuid,
  FpcItemScope Scope,
  VARIANT_BOOL *bExists
);

Parameters

sName
Required. String that specifies the name of the object.
sApplicationFilterGuid
Optional. String that specifies the GUID of the application filter if the object represents an application filter protocol.
Scope
Optional. A value from the FpcItemScope enumerated type. Has a default value of fpcArrayScope.

Return Values

bExists
A Boolean value that indicates whether an object that has the specified properties exists in the collection.

Remarks

Here is a VBScript example of how this method can be used. If the protocol "Archie" exists in ISA on the enterprise level, the following statement will return "TRUE".

FPC.GetContainingArray.ArrayPolicy.ProtocolRules(1).SpecifiedProtocols.Exists("Archie", "", fpcEnterpriseScope)

Applies To

FPCRefs


FPCRefs.Item Method

Retrieves the given FPCRef object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCRefs.Item( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  IFPCRef **pvItem
);

Parameters

lIndex
One-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCRef, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCRefs


FPCRefs.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCRefs.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCRefs


FPCRefs.Remove Method

Removes an FPCRef object from the collection.

VBScript Syntax[VBScript]

FPCRefs.Remove( lIndex )

C++ Syntax[C++]

HRESULT Remove(
  long lIndex
);

Parameters

lIndex
One-based index of the object to be removed.

Applies To

FPCRefs


FPCRefs.RemoveAll Method

Removes all FPCRef objects from the collection.

VBScript Syntax[VBScript]

FPCRefs.RemoveAll

C++ Syntax[C++]

HRESULT RemoveAll();

Applies To

FPCRefs


FPCRefs.RemoveSpecified Method

Removes an object identified by its properties.

VBScript Syntax[VBScript]

FPCRefs.RemoveSpecified ( sName, sApplicationFilterGuid, ItemScope )

C++ Syntax[C++]

HRESULT RemoveSpecified(
  BSTR sName,
  BSTR sApplicationFilterGuid,
  FpcItemScope ItemScope
);

Parameters

sName
Required. String that specifies the name of the object to be removed.
sApplicationFilterGuid
String that specifies the GUID of the application filter if the object being removed represents an application filter protocol.
ItemScope
A value from the FpcItemScope enumerated type.

Applies To

FPCRefs


FPCRefs.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCRefs.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCRefs


FPCRoutingRule Object

The FPCRoutingRule object represents a single routing rule of an ISA array. Routing rules redirect client requests within arrays of ISA servers. Routing rules determine whether a Web proxy client request is sent directly to the Internet, to another upstream proxy server, or to an alternate destination. You can use this object to access all attributes of each routing rule of the array, such as changing the destination set to which the rule applies or changing the URL to which to redirect, if that is the outcome of applying the rule.

This object is a member of the FPCRoutingRules collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCRoutingRule interface.

Methods

The following table lists the methods of the FPCRoutingRule object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetDestination | Sets the destinations to which the rule applies.

Properties

The following table lists the properties of the FPCRoutingRule object.

Property | Description
AppliesToDestination | Gets the type of destination to which the rule applies.
CacheResponseCondition | Gets or sets the conditions under which a response is cached.
Description | Gets or sets the description of the rule.
DestinationSetUsed | Gets or sets the name of the FPCDestinationSet collection used to define the destination to which the rule applies.
Enabled | Gets or sets whether this rule is enabled.
IsDefault | Gets whether the rule is preinstalled and cannot be deleted.
Name | Gets or sets the name of the rule.
NonSecureProtocolRedirection | Gets or sets the protocol used when delegating a request that came on a nonsecure channel.
Order | Gets the rule's order of execution in relation to the other rules.
PrimaryRoute | Gets a reference to an object that represents the specific proxy or array of the main (primary) route.
SecureProtocolRedirection | Gets or sets the protocol used when delegating a request that came on a secure channel.
SSLClientCertificate | Gets or sets the client certificate to use when authenticating with the publishing server.
SSLRequireSecureChannel | Gets or sets whether or not a secure channel is required.
UseCacheCondition | Gets or sets the situation in which a cache should be used instead of the routing action specified.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCRoutingRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRoutingRule.AppliesToDestination Property

Gets the type of destination to which the rule applies.

VBScript Syntax[VBScript]

[ DestinationSelection = ] FPCRoutingRule.AppliesToDestination

C++ Syntax[C++]

HRESULT get_AppliesToDestination(
  FpcDestinationSelection *pDestinationSelection
);

Parameters

DestinationSelection
Type of destination to which the rule applies. It can have a value of the FpcDestinationSelection enumerated type.

The property is read-only. It can be set by means of the SetDestination method.

Applies To

FPCRoutingRule


FPCRoutingRule.CacheResponseCondition Property

Gets or sets under what conditions a response is cached.

Note This property is not available in firewall mode. For more information, see ISA Server Modes.

VBScript Syntax[VBScript]

FPCRoutingRule.CacheResponseCondition [ = Condition ]

C++ Syntax[C++]

HRESULT get_CacheResponseCondition(
  FpcRouteCacheContent *pCondition
);

HRESULT put_CacheResponseCondition(
  FpcRouteCacheContent Condition
);

Parameters

Condition
Value from the FpcRouteCacheContent enumerated type. The value can be
  • fpcCacheAlways: the response is always cached, even if the request or response headers indicate that the response should not be cached.
  • fpcCacheOnlyIfNotDynamic: the response is cached only if the headers indicate that the response should be cached.
  • fpcNeverCache: the response is never cached.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.Description Property

Gets or sets the description of the rule.

VBScript Syntax[VBScript]

FPCRoutingRule.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the rule.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.DestinationSetUsed Property

Gets the name of the FPCRef object that is used to define the destination set to which the rule applies.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCRoutingRule.DestinationSetUsed

C++ Syntax[C++]

HRESULT get_DestinationSetUsed(
  IFPCRef **poFPCRef
);

Parameters

oFPCRef
Reference to a FPCRef object that specifies the name of the destination set to which the rule applies.

The property is read-only. It can be set through the SetDestination method.

Applies To

FPCRoutingRule


FPCRoutingRule.Enabled Property

Gets or sets whether this rule is enabled.

Note The default routing rule cannot be disabled.

VBScript Syntax[VBScript]

FPCRoutingRule.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies if the rule is enabled.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.IsDefault Property

Gets whether the rule is preinstalled, and cannot be deleted or have its position changed in the rule order.

VBScript Syntax[VBScript]

[ bDefault = ] FPCRoutingRule.IsDefault

C++ Syntax[C++]

HRESULT get_IsDefault(
  VARIANT_BOOL *pbDefault
);

Parameters

bDefault
Boolean value that specifies whether the rule is preinstalled.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRule.Name Property

Gets or sets the name of the rule.

VBScript Syntax[VBScript]

FPCRoutingRule.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the rule.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.NonSecureProtocolRedirection Property

Gets or sets the protocol to use when redirecting (bridging) HTTP requests that came on a non-secure channel.

VBScript Syntax[VBScript]

FPCRoutingRule.NonSecureProtocolRedirection [ = FpcPublishProtocolRedirectionType ]

C++ Syntax[C++]

HRESULT get_NonSecureProtocolRedirection(
  FpcPublishProtocolRedirectionType *pFpcPublishProtocolRedirectionType
);

HRESULT put_NonSecureProtocolRedirection(
  FpcPublishProtocolRedirectionType FpcPublishProtocolRedirectionType
);

Parameters

FpcPublishProtocolRedirectionType
Can have a value from the FpcPublishProtocolRedirectionType enumerated type.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.Order Property

Gets the rule's order of execution in relation to the other rules. You can set the routing rule's order by using the FPCRoutingRules.MoveDown and FPCRoutingRules.MoveUp methods.

VBScript Syntax[VBScript]

[ lOrder = ] FPCRoutingRule.Order

C++ Syntax[C++]

HRESULT get_Order(
  long *plOrder
);

Parameters

lOrder
Long value that specifies the order of execution.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRule.PrimaryRoute Property

Gets a reference to an object that represents the specific server or array of the main (primary) route.

VBScript Syntax[VBScript]

[ oFPCPrimaryRoute = ] FPCRoutingRule.PrimaryRoute

C++ Syntax[C++]

HRESULT get_PrimaryRoute(
  IFPCPrimaryRoute **poFPCPrimaryRoute
);

Parameters

oFPCPrimaryRoute
Reference to the FPCPrimaryRoute object.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRule.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCRoutingRule.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCRoutingRule


FPCRoutingRule.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

RoutingRule.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCRoutingRule


FPCRoutingRule.SecureProtocolRedirection Property

Gets or sets the protocol to use when redirecting (bridging) SSL requests that came on a secure channel.

VBScript Syntax[VBScript]

FPCRoutingRule.SecureProtocolRedirection [ = FpcPublishProtocolRedirectionType ]

C++ Syntax[C++]

HRESULT get_SecureProtocolRedirection(
  FpcPublishProtocolRedirectionType *pFpcPublishProtocolRedirectionType
);

HRESULT put_SecureProtocolRedirection(
  FpcPublishProtocolRedirectionType FpcPublishProtocolRedirectionType
);

Parameters

FpcPublishProtocolRedirectionType
Can have a value from the FpcPublishProtocolRedirectionType enumerated type.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.SetDestination Method

Sets the destinations to which the rule applies.

VBScript Syntax[VBScript]

FPCRoutingRule.SetDestination( DestType, sDestinationSet, ItemScope )

C++ Syntax[C++]

HRESULT SetDestination (
  FpcDestinationSelection DestType,
  BSTR sDestinationSet,
  FpcItemScope ItemScope
);

Parameters

DestType
[in] Required. Defines the type of destinations. Can have a value from the FpcDestinationSelection enumerated type.
sDestinationSet
[in] Optional. String that specifies the name of the destination set.
ItemScope
[in] Optional. Item scope. It can have a value from the FpcItemScope enumerated type. Has a default value of fpcArrayScope.

Applies To

FPCRoutingRule


FPCRoutingRule.SSLClientCertificate Property

Gets or sets the client certificate to use when the Web proxy service authenticates with the publishing server.

VBScript Syntax[VBScript]

FPCRoutingRule.SSLClientCertificate [ = oFPCSSLCertificate ]

C++ Syntax[C++]

HRESULT get_SSLClientCertificate (
  IFPCSSLCertificate **ppoFPCSSLCertificate
);

HRESULT put_SSLClientCertificate (
  IFPCSSLCertificate *poFPCSSLCertificate
);

Parameters

oFPCSSLCertificate
Reference to an FPCSSLCertificate object.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.SSLRequireSecureChannel Property

Gets or sets whether or not a secure channel is required.

VBScript Syntax[VBScript]

FPCRoutingRule.SSLRequireSecureChannel [ = FpcSSLRequireSecureChannelMode ]

C++ Syntax[C++]

HRESULT get_SSLRequireSecureChannel(
  FpcSSLRequireSecureChannelMode *pFpcSSLRequireSecureChannelMode
);

HRESULT put_SSLRequireSecureChannel(
  FpcSSLRequireSecureChannelMode FpcSSLRequireSecureChannelMode
);

Parameters

FpcSSLRequireSecureChannelMode
Value from the FpcSSLRequireSecureChannelMode enumerated type.

The property is read-write.

Applies To

FPCRoutingRule


FPCRoutingRule.UseCacheCondition Property

Gets or sets the condition in which a cache should be used rather than the routing action specified:

  • Use the cache only if a valid (unexpired) object exists in the cache.
  • Use the cache if any version of the object exists in the cache.
  • Always use the cache.

Note This property is not available in firewall mode. For more information see ISA Server Modes.

VBScript Syntax[VBScript]

FPCRoutingRule.UseCacheCondition [ = RouteCacheAction ]

C++ Syntax[C++]

HRESULT get_UseCacheCondition(
  FpcRouteCacheAction *pRouteCacheAction
);

HRESULT put_UseCacheCondition(
  FpcRouteCacheAction RouteCacheAction
);

Parameters

RouteCacheAction
Type of cache using behavior. It can have a value of the FpcRouteCacheAction enumerated type.

The property is read-write.

Remarks

You can configure whether caching takes precedence over routing; that is, you can specify whether an object should be retrieved from the ISA Server cache or whether the request should be routed to the Internet or another proxy server.

Applies To

FPCRoutingRule


FPCRoutingRule.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCRoutingRule object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCRoutingRule.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCRoutingRule


FPCRoutingRules Collection

The FPCRoutingRules collection provides access to a group of FPCRoutingRule objects in an ISA array. Routing rules redirect client requests within arrays of ISA servers. Routing rules determine whether a Web proxy client request is sent directly to the Internet, to another upstream proxy server, or to an alternate destination. By using the MoveUp and MoveDown methods, you can adjust the order in which the routing rules in the group apply.

When you install ISA Server, it configures a default routing rule. The default rule is initially configured so that all requested objects should be retrieved from the ISA Server cache. If the object is not in the cache, then it should be retrieved directly from the Internet.The default routing rule is ordered last and its in the order cannot be changed.You can modify the default routing rule's action and how it redirects outgoing Web requests, but you cannot delete it.

The FPCRoutingRules collection is a property of the FPCNetworkConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCRoutingRules interface.

Methods

The following table lists the methods of the FPCRoutingRules collection.

Method | Description
Add | Creates a new routing rule, adds it to the collection, and returns a reference to it.
Item | Retrieves the given FPCRoutingRule object from the collection.
MoveDown | Moves the given rule down the ladder of execution.
MoveUp | Moves the given rule up the ladder of execution.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a routing rules object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCRouting Rules collection.

Property | Description
Count | Gets the number of routing rule objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCRoutingRules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCRoutingRules.Add Method

Creates a new routing rule, adds it to the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCRoutingRule = ] FPCRoutingRules.Add( sRuleName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sRuleName,
  IFPCRoutingRule **ppoFPCRoutingRule
);

Parameters

sRuleName
Required. String that specifies the name of the routing rule.

Return Value

oFPCRoutingRule
Reference to the new FPCRoutingRule object.

Applies To

FPCRoutingRules


FPCRoutingRules.Count Property

Gets the number of routing rule objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCRoutingRules.Count

C++ Syntax[C++]

HRESULT Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCRoutingRule objects.

The property is read-only.

Applies To

FPCRoutingRules


FPCRoutingRules.Item Method

Retrieves the given FPCRoutingRule object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCRoutingRules.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCRoutingRule **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCRoutingRule, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCRoutingRules


FPCRoutingRules.MoveDown Method

Moves the given rule down the ladder of execution.

VBScript Syntax[VBScript]

FPCRoutingRules.MoveDown( lIndex )

C++ Syntax[C++]

HRESULT MoveDown(
  long lIndex
);

Parameters

lIndex
Required. Index (current order) of the rule to move down.

Applies To

FPCRoutingRules

See Also

MoveUp


FPCRoutingRules.MoveUp Method

Moves the given rule up the ladder of execution.

VBScript Syntax[VBScript]

FPCRoutingRules.MoveUp( lIndex )

C++ Syntax[C++]

HRESULT MoveUp(
  long lIndex
);

Parameters

lIndex
Required. Index (current order) of the rule to move up.

Applies To

FPCRoutingRules

See Also

MoveDown


FPCRoutingRules.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCRoutingRules.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCRoutingRules


FPCRoutingRules.Remove Method

Removes an FPCRoutingRule object from the collection.

VBScript Syntax[VBScript]

FPCRoutingRules.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCRoutingRules


FPCRoutingRules.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCRoutingRules.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCRoutingRules


FPCRoutingRules.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCRoutingRules collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCRoutingRules.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCRoutingRules


FPCSchedule Object

The FPCSchedule object defines a schedule. A schedule is defined by groups of hours defined for each day of the week. Each day of the week can have different hour blocks defined. Schedules are applied by ISA to define a set of hours during which a certain configuration detail, such as a site and content rule, applies.

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example, the hour designated by 2_PM is the one-hour time block of between 2 P.M. and 3 P.M.

The FPCSchedule object is a member of the FPCSchedules collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCSchedule interface.

Methods

The following table lists the methods of the FPCSchedule object.

Method | Description
IsSet | Returns a Boolean variable indicating whether every hour in the given set is part of the schedule.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
Set | Adds a set of hours to the schedule.
UnSet | Removes a set of hours from the schedule.

Properties

The following table lists the properties of the FPCSchedule object.

Property | Description
Description | Gets or sets the description of the schedule.
Name | Gets or sets the name of the schedule.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCSchedule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSchedule.Description Property

Gets or sets the description of the schedule.

VBScript Syntax[VBScript]

FPCSchedule.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the schedule.

The property is read-write.

Applies To

FPCSchedule


FPCSchedule.IsSet Method

Returns a Boolean variable indicating whether every hour in the given set is part of the schedule.

VBScript Syntax[VBScript]

[ bIsSet = ] FPCSchedule.IsSet( Day, Hour )

C++ Syntax[C++]

HRESULT IsSet(
  FpcScheduleDays Day,
  FpcScheduleHours Hour,
  VARIANT_BOOL *pbIsSet
);

Parameters

Day
Value from the FpcScheduleDays enumerated type that specifies a day. It can be ALL_WEEK, SUN, MON, and so on.
Hour
Value from the FpcScheduleHours enumerated type that specifies an hour or hours. It can be ALL_DAY, AM_0, AM_1, PM_1, PM_2, and so on.

Return Values

bIsSet
Boolean value that receives TRUE if every hour in the set specified by the Day and Hour parameters is part of the schedule; FALSE otherwise.

Remarks

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example, the hour designated by 2_PM is the one-hour time block of between 2 P.M. and 3 P.M.

Applies To

FPCSchedule

See Also

Set, UnSet


FPCSchedule.Name Property

Gets or sets the name of the schedule.

VBScript Syntax[VBScript]

FPCSchedule.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the schedule name.

The property is read-write.

Applies To

FPCSchedule


FPCSchedule.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCSchedule.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCSchedule


FPCSchedule.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCSchedule.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCSchedule


FPCSchedule.Set Method

Adds a set of hours to the schedule.

VBScript Syntax[VBScript]

FPCSchedule.Set( Day, Hour )

C++ Syntax[C++]

HRESULT Set(
  FpcScheduleDays Day,
  FpcScheduleHours Hour
);

Parameters

Day
Value from the FpcScheduleDays enumerated type that specifies a day. It can be ALL_WEEK, SUN, MON, and so on.
Hour
Value from the FpcScheduleHours enumerated type that specifies an hour or hours. It can be ALL_DAY, AM_0, AM_1, PM_1, PM_2, and so on.

Example

The following example adds "3AM on Sunday" to the set:

Set(SUN, AM_3)

The following example adds "6AM on every day" to the set:

Set(ALL_WEEK, AM_6)

The following example adds all of Monday to the set:

Set(MON, ALL_DAY)

The following example adds all hours of the week to the set:

Set(ALL_WEEK, ALL_DAY)

Remarks

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example, the hour designated by 2_PM is the one-hour time block of between 2 P.M. and 3 P.M.

Applies To

FPCSchedule

See Also

IsSet, UnSet


FPCSchedule.UnSet Method

Removes a set of hours from the schedule.

VBScript Syntax[VBScript]

FPCSchedule.UnSet( Day, Hour )

C++ Syntax[C++]

HRESULT UnSet(
  FpcScheduleDays Day,
  FpcScheduleHours Hour
);

Parameters

Day
Value from the FpcScheduleDays enumerated type that specifies a day. It can be ALL_WEEK, SUN, MON, and so on.
Hour
Value from the FpcScheduleHours enumerated type that specifies an hour or hours. It can be ALL_DAY, AM_0, AM_1, PM_1, PM_2, and so on.

Remarks

The hour blocks defined by a schedule include the specified time and the one-hour block beyond that time. For example the hour designated by 2_PM is the one-hour time block of between 2 P.M. and 3 P.M.

Applies To

FPCSchedule

See Also

IsSet, Set


FPCSchedule.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCSchedule object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCSchedule.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSchedule


FPCSchedules Collection

The FPCSchedules collection is a collection of FPCSchedule objects. Each object within this schedule defines a schedule. A schedule is defined by groups of hours defined for each day of the week. Each day of the week can have different hour blocks defined. Schedules are used by ISA to define a set of hours during which a certain configuration, such as a site and content rule, applies.

This collection is a property of the FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCSchedules interface.

Methods

The following table lists the methods of the FPCSchedules collection.

Method | Description
Add | Creates a new schedule in the collection and returns a reference to it.
Item | Retrieves the given FPCSchedule object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a schedule from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCSchedules collection.

Property | Description
Count | Gets the number of schedule objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCSchedules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSchedules.Add Method

Creates a new schedule in the collection and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCSchedule = ] FPCSchedules.Add( sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  IFPCSchedule **ppoFPCSchedule
);

Parameters

sName
String that specifies the name of the new schedule.

Parameters

oFPCSchedule
Reference to the FPCSchedule object.

Remarks

Newly created schedules do not contain any defined hour blocks. You can define hour blocks with the methods of the individual FPCSchedule object.

The additional FPCSchedule object added by this method is not saved to persistent storage until after the Save method is called.

Applies To

FPCSchedules


FPCSchedules.Count Property

Gets the number of schedule objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCSchedules.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCSchedule objects.

The property is read-only.

Applies To

FPCSchedules


FPCSchedules.Item Method

Returns the given FPCSchedule object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCSchedules.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCSchedule **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCSchedule, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCSchedules


FPCSchedules.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCSchedules.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCSchedules


FPCSchedules.Remove Method

Removes a schedule from the collection.

VBScript Syntax[VBScript]

FPCSchedules.Remove( vIndex, bVerify )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
  VARIANT_BOOL bVerify
);

Parameters

vIndex
Required. Name or one-based index of the FPCSchedule object to remove.
bVerify
Optional. Boolean value that specifies whether COM verifies, prior to removal, if the schedule is used by a rule. The default value is TRUE.

Applies To

FPCSchedules


FPCSchedules.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCSchedules.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCSchedules


FPCSchedules.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCSchedules collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCSchedules.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSchedules


FPCScheduledContentDownload Collection

The FPCScheduledContentDownload collection provides access to all FPCScheduledContentDownloadConfig objects of an ISA Server computer. This collection allows you to create a list of predefined fetching tasks.

The FPCScheduledContentDownload collection is a property of the FPCCacheConfiguration object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCScheduledContentDownload interface.

Methods

The following table lists the methods of the FPCScheduledContentDownload collection.

Method | Description
Add | Creates a new FPCScheduledContentDownloadConfig object in the list and returns a reference to it.
Item | Retrieves the given FPCScheduledContentDownloadConfig object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCScheduledContentDownloadConfig object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCScheduledContentDownload collection.

Property | Description
Count | Gets the number of FPCScheduledContentDownloadConfig objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCScheduledContentDownload.Add Method

Creates a new FPCScheduledContentDownloadConfig object in the list and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCScheduledContentDownloadConfig = ] FPCScheduledContentDownload.Add( sName, sURL )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  BSTR sURL,
  IFPCScheduledContentDownloadConfig **ppoFPCScheduledContentDownloadConfig
);

Parameters

sName
Required. String that specifies the name of a new FPCScheduledContentDownloadConfig object.
sURL
Required. String that specifies the URL.

Return Value

oFPCScheduledContentDownloadConfig
Returns a reference to the new FPCScheduledContentDownloadConfig object.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Count Property

Gets the number of FPCScheduledContentDownloadConfig objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCScheduledContentDownload.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCScheduledContentDownloadConfig objects.

The property is read-only.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Item Method

Retrieves the FPCScheduledContentDownloadConfig object from the collection, specified by the method's index parameter.

VBScript Syntax[VBScript]

[ vItem = ] FPCScheduledContentDownload.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCScheduledContentDownloadConfig **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCScheduledContentDownloadConfig, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCScheduledContentDownload.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Remove Method

Removes an FPCScheduledContentDownloadConfig object from the collection.

VBScript Syntax[VBScript]

FPCScheduledContentDownload.Remove( vItem )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vItem
);

Parameters

vItem
Required. One-based index or name of the object to remove.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCScheduledContentDownload.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownload.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCScheduledContentDownload object's storage. The VendorParameterSets property is designed to allow third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCScheduledContentDownload.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCScheduledContentDownload


FPCScheduledContentDownloadConfig Object

The FPCScheduledContentDownloadConfig object defines each prefetch task contained in the FPCScheduledContentDownload collection. This collection allows you to create a list of predefined fetching tasks.

The prefetching feature of the ISA Server cache lets you download HTTP content directly to the ISA Server cache, upon request or as scheduled. Prefetching allows you to update the ISA Server cache with HTTP content that you anticipate will be requested by clients in your organization.

You can configure the content that ISA Server should download. You can also schedule when the content should be cached, available for access directly from the ISA Server cache, rather than from the Internet.

You can use cache prefetching to schedule downloads of HTTP files from a Web site to a local cache. You can download a single URL, multiple URLs, or an entire Web site according to a schedule you specify.

The FPCScheduledContentDownloadConfig object is a member of the FPCScheduledContentDownload collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCScheduledContentDownloadConfig interface.

Methods

The following table lists the methods of the FPCScheduledContentDownloadConfig object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetTaskPeriod | Sets the values retrieved through the TaskPeriod and ScheduleDays properties of the FPCScheduledContentDownloadConfig object.

Properties

The following table lists the properties of the FPCScheduledContentDownloadConfig object.

Property | Description
Description | Gets or sets the description of the FPCScheduledContentDownloadConfig object.
Enabled | Gets or sets whether the configuration is enabled.
FetchUrlFlagForce | Gets or sets the FETCH_FORCE_CACHE flag, which is passed to the FetchUrl method.
FetchUrlFlagNoArrayRoute | Gets or sets the FETCH_NO_ARRAY_ROUTING flag, which is passed to FetchUrl.
FetchUrlFlagSync | Gets or sets the FETCH_SYNCHRONOUS flag, which is passed to FetchUrl.
FetchUrlFlagTtlIfNone | Gets or sets the FETCH_TTL_IF_NONE flag, which is passed to FetchUrl.
FetchUrlFlagTtlOverride | Gets or sets the FETCH_TTL_OVERRIDE flag, which is passed to FetchUrl.
MaxDepth | Gets or sets the upper limit of depth to fetch.
MaxPages | Gets or sets the upper limit of size to fetch. Must be set to a positive integer.
Name | Gets or sets the name of the FPCScheduledContentDownloadConfig object.
SchedTimeHour | Gets or sets the time (hour) to start fetching.
SchedTimeMinute | Gets or sets the time (minutes) to start fetching.
ScheduleDays | Gets the days of the week on which the fetch is done (each day is represented by a bit: Sunday—bit 0, Monday—bit 1, and so forth).
StartDateDay | Gets or sets the date (day) to start fetching.
StartDateMonth | Gets or sets the date (month) to start fetching.
StartDateYear | Gets or sets the date (year) to start fetching.
StayInDomain | Gets or sets whether to fetch from the initial domain only or from other domains as well.
TaskPeriod | Gets the period of time between two prefetches.
TTL | Gets or sets the Time-To-Live (TTL) setting of the pages to be fetched.
URL | Gets or sets the URL to be fetched.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCScheduledContentDownloadConfig object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCScheduledContentDownloadConfig.Description Property

Gets or sets the description of the FPCScheduledContentDownloadConfig object.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Enabled Property

Gets or sets whether the configuration is enabled.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the configuration is enabled.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagForce Property

Gets or sets the FETCH_FORCE_CACHE flag, which is passed to the FetchUrl method.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.FetchUrlFlagForce [ = bFetchUrlFlagForce ]

C++ Syntax[C++]

HRESULT get_FetchUrlFlagForce(
  VARIANT_BOOL *pbFetchUrlFlagForce
);

HRESULT put_FetchUrlFlagForce(
  VARIANT_BOOL bFetchUrlFlagForce
);

Parameters

bFetchUrlFlagForce
Boolean value that specifies the flag. TRUE indicates that the flag is set.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagNoArrayRoute Property

Gets or sets the FETCH_NO_ARRAY_ROUTING flag, which is passed to the FetchUrl method.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.FetchUrlFlagNoArrayRoute [ = bFetchUrlFlagNoArrayRoute ]

C++ Syntax[C++]

HRESULT get_FetchUrlFlagNoArrayRoute(
  VARIANT_BOOL *pbFetchUrlFlagNoArrayRoute
);

HRESULT put_FetchUrlFlagNoArrayRoute(
  VARIANT_BOOL bFetchUrlFlagNoArrayRoute
);

Parameters

bFetchUrlFlagNoArrayRoute
Boolean value that specifies the flag. TRUE indicates that the flag is set.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagSync Property

Gets or sets the FETCH_SYNCHRONOUS flag, which is passed to the FetchUrl method.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.FetchUrlFlagSync [ = bFetchUrlFlagSync ]

C++ Syntax[C++]

HRESULT get_FetchUrlFlagSync(
  VARIANT_BOOL *pbFetchUrlFlagSync
);

HRESULT put_FetchUrlFlagSync(
  VARIANT_BOOL bFetchUrlFlagSync
);

Parameters

bFetchUrlFlagSync
Boolean value that specifies the flag. TRUE indicates that the flag is set.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagTtlIfNone Property

Gets or sets the FETCH_TTL_IF_NONE flag, which is passed to the FetchUrl method.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.FetchUrlFlagTtlIfNone [ = bFetchUrlFlagTtlIfNone ]

C++ Syntax[C++]

HRESULT get_FetchUrlFlagTtlIfNone(
  VARIANT_BOOL *pbFetchUrlFlagTtlIfNone
);

HRESULT put_FetchUrlFlagTtlIfNone(
  VARIANT_BOOL bFetchUrlFlagTtlIfNone
);

Parameters

bFetchUrlFlagTtlIfNone
Boolean value that specifies the flag. TRUE indicates that the flag is set.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.FetchUrlFlagTtlOverride Property

Gets or sets the FETCH_TTL_OVERRIDE flag, which is passed to the FetchUrl method.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.FetchUrlFlagTtlOverride [ = bFetchUrlFlagTtlOverride ]

C++ Syntax[C++]

HRESULT get_FetchUrlFlagTtlOverride(
  VARIANT_BOOL *pbFetchUrlFlagTtlOverride
);

HRESULT put_FetchUrlFlagTtlOverride(
  VARIANT_BOOL bFetchUrlFlagTtlOverride
);

Parameters

bFetchUrlFlagTtlOverride
Boolean value that specifies the flag. TRUE indicates that the flag is set.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.MaxDepth Property

Gets or sets the upper limit of depth to fetch. Depth refers to the number of links that will be followed when downloading content.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.MaxDepth [ = lMaxDepth ]

C++ Syntax[C++]

HRESULT get_MaxDepth(
  long *plMaxDepth
);

HRESULT put_MaxDepth(
  long lMaxDepth
);

Parameters

lMaxDepth
Long value that specifies the upper limit of term-link depth.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.MaxPages Property

Gets or sets the integer that specifies the upper limit in terms of total cache-object size in kilobytes.

Note Must be set to a positive integer. The scheduled content download service will not allow an infinite number of pages to be retrieved.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.MaxPages [ = lMaxPages ]

C++ Syntax[C++]

HRESULT get_MaxPages(
  long *plMaxPages
);

HRESULT put_MaxPages(
  long lMaxPages
);

Parameters

lMaxPages
Long value that specifies the upper limit in terms of total cache-object size in kilobytes.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Name Property

Gets or sets the name of the FPCScheduledContentDownloadConfig object.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the FPCScheduledContentDownloadConfig object.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.SchedTimeHour Property

Gets or sets the time, in full hours, to start fetching.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.SchedTimeHour [ = lSchedTimeHour ]

C++ Syntax[C++]

HRESULT get_SchedTimeHour(
  long *plSchedTimeHour
);

HRESULT put_SchedTimeHour(
  long lSchedTimeHour
);

Parameters

lSchedTimeHour
Long value that specifies the hour to start fetching.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.SchedTimeMinute Property

Gets or sets the time in minutes to start fetching.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.SchedTimeMinute [ = lSchedTimeMinute ]

C++ Syntax[C++]

HRESULT SchedTimeMinute(
  long *plSchedTimeMinute
);

HRESULT SchedTimeMinute(
  long lSchedTimeMinute
);

Parameters

lSchedTimeMinute
Long value that specifies the minute to start fetching.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.ScheduleDays Property

Retrieves the days of weeks in which to perform the fetching task. Each day is represented by a bit. Sunday is bit 0, Monday is bit 1, and so forth. The value of this property is set through the SetTaskPeriod method.

VBScript Syntax[VBScript]

[ Days = ] FPCScheduledContentDownloadConfig.ScheduleDays

C++ Syntax[C++]

HRESULT ScheduleDays(
  FpcDaysOfWeek *pDays
);

Parameters

Days
Value from the FpcScheduleDays enumerated type that specifies a day. It can be ALL_WEEK, SUN, MON, and so on.

The property is read-only.

Example

The following code sets the ScheduleDays property to equal Sunday, Tuesday, and Thursday.

FPCScheduledContentDownloadConfig.ScheduleDays = 0x15

0x15 is 15 in hexadecimal (which is 21 in decimal). In binary it is 10101. The right bit represents Sunday. It is set to one, so Sunday is set. The second bit represents Monday. Its value is zero, so Monday is not set.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.SetTaskPeriod Method

Sets the values retrieved through the TaskPeriod and ScheduleDays properties of the FPCScheduledContentDownloadConfig object.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.SetTaskPeriod ( TaskPeriod, ScheduleDays )

C++ Syntax[C++]

HRESULT SetTaskPeriod(
  FpcScheduledContentDownloadPeriod TaskPeriod,
  FpcDaysOfWeek ScheduleDays
);

Parameters

TaskPeriod
Task period. It can have a value from the FpcScheduledContentDownloadPeriod enumerated type.
ScheduleDays
Optional. A value from the FpcScheduleDays enumerated type. This parameter will be used if TaskPeriod is set to the DownloadSpecifiedDaysOfWeek value of the FpcScheduledContentDownloadPeriod enumerated type.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StartDateDay Property

Gets or sets the date, as a day, to start the scheduled content download.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.StartDateDay [ = lStartDateDay ]

C++ Syntax[C++]

HRESULT get_StartDateDay(
  long *plStartDateDay
);

HRESULT put_StartDateDay(
  long lStartDateDay
);

Parameters

lStartDateDay
Long value that specifies the day.

The property is read-write.

Remarks

The date to start the scheduled content download is in the form of dd.mm.yyyy, where dd equals the two-digit day, mm equals the two-digit month, and yyyy equals the four-digit year. The day is set by the StartDateDay property, the month is set by the StartDateMonth property, and the year is set by the StartDateYear property.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StartDateMonth Property

Gets or sets the month to start the scheduled content download.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.StartDateMonth [ = lStartDateMonth ]

C++ Syntax[C++]

HRESULT get_StartDateMonth(
  long *plStartDateMonth
);

HRESULT put_StartDateMonth(
  long lStartDateMonth
);

Parameters

lStartDateMonth
Long value that specifies the month.

The property is read-write.

Remarks

The date to start the scheduled content download is in the form of dd.mm.yyyy, where dd equals the two-digit day, mm equals the two-digit month, and yyyy equals the four-digit year. The day is set by the StartDateDay property, the month is set by the StartDateMonth property, and the year is set by the StartDateYear property.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StartDateYear Property

Gets or sets the year to start the scheduled content download.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.StartDateYear [ = lStartDateYear ]

C++ Syntax[C++]

HRESULT get_StartDateYear(
  long *plStartDateYear
);

HRESULT put_StartDateYear(
  long lStartDateYear
);

Parameters

lStartDateYear
Long value that specifies the year.

The property is read-write.

Remarks

The date to start the scheduled content download is in the form of dd.mm.yyyy, where dd equals the two-digit day, mm equals the two-digit month, and yyyy equals the four-digit year. The day is set by the StartDateDay property, the month is set by the StartDateMonth property, and the year is set by the StartDateYear property.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.StayInDomain Property

Gets or sets whether to perform the the scheduled content download from the initial domain only, or from other domains as well.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.StayInDomain [ = bStayInDomain ]

C++ Syntax[C++]

HRESULT get_StayInDomain(
  VARIANT_BOOL *pbStayInDomain
);

HRESULT put_StayInDomain(
  VARIANT_BOOL bStayInDomain
);

Parameters

bStayInDomain
Boolean value that has either of these settings:
Setting | Meaning
TRUE | The traversal will remain in the domain of the root URL.
FALSE | Scheduled content downloadfrom initial domain and other domains.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.TaskPeriod Property

Gets the period of time between two prefetch actions by an ISA server. TaskPeriod is set through the SetTaskPeriod method.

VBScript Syntax[VBScript]

[ ScheduledContentDownloadPeriod = ] FPCScheduledContentDownloadConfig.TaskPeriod

C++ Syntax[C++]

HRESULT get_TaskPeriod(
  FpcScheduledContentDownloadPeriod *pScheduledContentDownloadPeriod
);

Parameters

ScheduledContentDownloadPeriod
A value from the FpcScheduledContentDownloadPeriod enumerated type.
The property is read-only.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.TTL Property

Gets or sets the Time-To-Live (TTL) setting of the pages to be fetched.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.TTL [ = lTTL ]

C++ Syntax[C++]

HRESULT get_TTL(
  long *plTTL
);

HRESULT put_TTL(
  long lTTL
);

Parameters

lTTL
Long value that specifies the TTL.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.URL Property

Gets or sets the URL to be downloaded.

VBScript Syntax[VBScript]

FPCScheduledContentDownloadConfig.URL [ = sURL ]

C++ Syntax[C++]

HRESULT get_URL(
  BSTR *psURL
);

HRESULT put_URL(
  BSTR sURL
);

Parameters

sURL
String that specifies the URL to be downloaded.

The property is read-write.

Applies To

FPCScheduledContentDownloadConfig


FPCScheduledContentDownloadConfig.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCScheduledContentDownloadConfig object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCScheduledContentDownloadConfig.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCScheduledContentDownloadConfig


FPCSecurityDescriptor Object

The FPCSecurityDescriptor object allows you to access security settings of ISA objects. You can also use it to make copies of a security descriptor. This object is a property of every object that supports security settings. Specifically, the FPCSecurityDescriptor object is a property of the FPCArray, FPCEnterprise, and the FPCEnterprisePolicy objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCSecurityDescriptor interface.

Remarks

The following table lists the default permissions assigned to each object upon installation.

Object | Permissions
Enterprise | Enterprise Admins, and local system have Full Control permission. All authenticated users have Read permission.
Enterprise policy | Enterprise Admins, and local system have Full Control permission. All authenticated users have Read permission.
Array | Enterprise Admins, Domain Admins, local Administrators, and local system have Full Control permission. All authenticated users have Read permission.
Alerts | Enterprise Admins, Domain Admins, local Administrators, and local system have Read Alerts Information and Reset Alerts permissions. All authenticated users have Read Alerts Information permission.
Sessions | Enterprise Admins, Domain Admins, local Administrators, and local system have Read Sessions Information and Stop Sessions permissions. All authenticated users have Read Sessions Information permission.

Methods

The following table lists the methods of the FPCSecurityDescriptor object.

Method | Description
CopySecurityDescriptor | Returns a copy of the current FPCSecurityDescriptor object.

Properties

The following table lists the properties of the FPCSecurityDescriptor object.

Property | Description
Control | Gets or sets flags that qualify the meaning of the security descriptor.
DaclDefaulted | Gets or sets a flag to indicate whether the DACL is derived from a default mechanism rather than provided explicitly by the original provider of the security descriptor.
DiscretionaryAcl | Gets or sets the values of a discretionary access control list (DACL) that specifies types of access allowed to the object for specified users and groups.
Group | Gets or sets a string that specifies the group to which the owner's security identifier (ID) belongs.
GroupDefaulted | Gets or sets a flag that indicates whether the group information is derived from a default mechanism rather than provided explicitly by the original provider of the security descriptor.
Owner | Gets or sets the owner of the object.
OwnerDefaulted | Gets or sets a flag that indicates whether the owner information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.
Revision | Gets or sets the revision level of the security descriptor.
SaclDefaulted | Gets or sets a flag that indicates whether the system access control list (SACL) is derived from a default mechanism rather than by the original provider of the security descriptor explicitly.
SystemAcl | Gets or sets an SACL used to generate audit records for the object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSecurityDescriptor.Control Property

Gets or sets flags that qualify the meaning of the security descriptor. Values are similar to those in the Win32 SECURITY_DESCRIPTOR_CONTROL structure. See MSDN for more information.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.Control [ = lControl ]

C++ Syntax[C++]

HRESULT get_Control(
  long *plControl
);

HRESULT put_Control(
  long lControl
);

Parameters

lControl
Long value that qualifies the meaning of the security descriptor by using a combination of bit values from the FpcSDControl enumerated type.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.CopySecurityDescriptor Method

Returns a copy of the current FPCSecurityDescriptor object.

VBScript Syntax[VBScript]

[ oFPCSecurityDescriptor = ] FPCSecurityDescriptor.CopySecurityDescriptor()

C++ Syntax[C++]

HRESULT CopySecurityDescriptor(
  IDispatch **ppoFPCSecurityDescriptor
);

Return Value

oFPCSecurityDescriptor
Reference to an FPCSecurityDescriptor object.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.DaclDefaulted Property

Gets or sets a flag to indicate whether the discretionary access control list (DACL) is derived from a default mechanism rather than provided by the original provider of the security descriptor. For example, if an object's creator does not specify a DACL, the object receives the default DACL from the creator's access token. This flag can affect how the system treats the DACL with respect to access control entry (ACE) inheritance. The system ignores this flag if the SE_DACL_PRESENT flag is not set.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.DaclDefaulted [ = bDaclDefaulted ]

C++ Syntax[C++]

HRESULT get_DaclDefaulted(
  VARIANT_BOOL *bDaclDefaulted
);

HRESULT put_DaclDefaulted(
  VARIANT_BOOL bDaclDefaulted
);

Parameters

bDaclDefaulted
A Boolean value that indicates whether the DACL is derived from a default mechanism.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.DiscretionaryAcl Property

Gets or sets the values of a discretionary access control list (DACL) that specifies types of access allowed to the object for specified users and groups.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.DiscretionaryAcl [ = collFPCAccessControlList ]

C++ Syntax[C++]

HRESULT get_DiscretionaryAcl(
  IFPCAccessControlList **pcollFPCAccessControlList
);

HRESULT put_DiscretionaryAcl(
  IFPCAccessControlList *pcollFPCAccessControlList
);

Parameters

collFPCAccessControlList
Reference to an FPCAccessControlList collection that specifies types of access allowed to the object for specified users and groups.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.Group Property

Gets or sets a string that specifies the group to which the owner's security identifier (ID) belongs.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.Group [ = sGroup ]

C++ Syntax[C++]

HRESULT get_Group(
  BSTR *psGroup
);

HRESULT put_Group(
  BSTR sGroup
);

Parameters

sGroup
String value that specifies the group to which the owner's security ID belongs.

This value can take the following forms:

  • Domain account (the logon name used in some versions of Windows® NT) of the form domain\accountname. Domain is the name of the Windows NT domain that contains the user, and accountname is the sAMAccountName property of the specified user, for example: Microsoft\jeffsmit.
  • Well-known security principal that represents special identities defined by the Windows NT security system, such as everyone, local system, principal self, authenticated user, creator owner, and so on. The objects representing the well-known security principals are stored in the WellKnown Security Principals container beneath the Configuration container.
  • Built-in group that represent the built-in user groups defined by the Windows NT security system. It has the form BUILTIN\groupname where groupname is the name of the built-in user group, for example, BUILTIN\Administrators. The objects representing the built-in groups are stored in the Builtin container beneath the domain container.
  • SID (string format) of the specified user, which is the objectSID property of the specified user, for example: S-1-5-32-548. You can convert this to string form by using the ConvertSidToStringSid function in the Win32 Security API.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.GroupDefaulted Property

Gets or sets a flag that indicates whether the group information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.GroupDefaulted [ = bGroupDefaulted ]

C++ Syntax[C++]

HRESULT get_GroupDefaulted(
  VARIANT_BOOL *pbGroupDefaulted
);

HRESULT put_GroupDefaulted(
  VARIANT_BOOL bGroupDefaulted
);

Parameters

bGroupDefaulted
A Boolean value that indicates whether the group information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.Owner Property

Gets or sets the owner of the object.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.Owner [ = sOwner ]

C++ Syntax[C++]

HRESULT get_Owner(
BSTR *psOwner
);

HRESULT put_Owner(
  BSTR sOwner
);

Parameters

sOwner
String value that specifies the owner of the object. This value can take the following forms:
  • Domain account (the logon name used in some versions of Windows NT) of the form domain\accountname. Domain is the name of the Windows NT domain that contains the user, and accountname is the sAMAccountName property of the specified user, for example: Microsoft\jeffsmit.
  • Well-known security principal that represents special identities defined by the Windows NT security system, such as everyone, local system, principal self, authenticated user, creator owner, and so on. The objects representing the well-known security principals are stored in the WellKnown Security Principals container beneath the Configuration container.
  • Built-in group that represent the built-in user groups defined by the Windows NT security system. It has the form BUILTIN\groupname where groupname is the name of the built-in user group, for example, BUILTIN\Administrators. The objects representing the built-in groups are stored in the Builtin container beneath the domain container.
  • SID (string format) of the specified user, which is the objectSID property of the specified user, for example: S-1-5-32-548. You can convert this to string form by using the ConvertSidToStringSid function in the Win32 Security API.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.OwnerDefaulted Property

Gets or sets a flag that indicates whether the owner information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.OwnerDefaulted [ = bOwnerDefaulted ]

C++ Syntax[C++]

HRESULT get_OwnerDefaulted(
  VARIANT_BOOL *pbOwnerDefaulted
);

HRESULT put_OwnerDefaulted(
  VARIANT_BOOL bOwnerDefaulted
);

Parameters

bOwnerDefaulted
A Boolean value that indicates whether the owner information is derived from a default mechanism rather than from the original provider of the security descriptor explicitly.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.Revision Property

Gets or sets the revision level of the security descriptor.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.Revision [ = lRevision ]

C++ Syntax[C++]

HRESULT get_Revision(
  long *plRevision
);

HRESULT put_Revision(
  long lRevision
);

Parameters

lRevision
Long value that is a reference to the revision level of the security descriptor.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.SaclDefaulted Property

Gets or sets a flag that indicates whether the system access control list (SACL) is derived from a default mechanism rather than from the original provider of the security descriptor explicitly. This flag can affect how the system treats the SACL, with respect to ACE inheritance. The system ignores this flag if the SE_SACL_PRESENT flag is not set.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.SaclDefaulted [ = bSaclDefaulted ]

C++ Syntax[C++]

HRESULT get_SaclDefaulted(
  VARIANT_BOOL *pbSaclDefaulted
);

HRESULT put_SaclDefaulted(
  VARIANT_BOOL bSaclDefaulted
);

Parameters

bSaclDefaulted
Boolean value that indicates whether the SACL is derived from a default mechanism.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCSecurityDescriptor.SystemAcl Property

Gets or sets a system access control list (SACL) used to generate audit records for the object.

VBScript Syntax[VBScript]

FPCSecurityDescriptor.SystemAcl [ = collFPCAccessControlList ]

C++ Syntax[C++]

HRESULT get_SystemAcl(
  IFPCAccessControlList **pcollFPCAccessControlList
);

HRESULT put_SystemAcl(
  IFPCAccessControlList *pcollFPCAccessControlList
);

Parameters

collFPCAccessControlList
Reference to an FPCAccessControlList collection used to generate audit records for the object.

The property is read-write.

Applies To

FPCSecurityDescriptor


FPCServer Object

The FPCServer object holds a single ISA Server computer within a server array. Each object has multiple properties that are used to set configuration settings. By using this object, you can programmatically access drives, available network interface cards (NICs), product information, and other generic server attributes such as a server's name and description.

You use this object to access server-specific configuration from a server within the array. Array-specific information is accessed through the FPCServers collection.

This object is a member of the FPCServers collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCServer interface.

Methods

The following table lists the methods of the FPCServer object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
RestartServices | Restarts all previously stopped services.
Save | Saves the object's configuration to persistent storage.
StartFirewallService | Starts Firewall service.
StartScheduledContentDownloadService | Starts the scheduled content download service.
StartWebProxyService | Starts Web proxy service.
StopAllServices | Stops all the running ISA services, and the services that depend on those ISA services, on the current server.
StopFirewallService | Stops the Firewall service.
StopScheduledContentDownloadService | Stops the scheduled content download service.
StopWebProxyService | Stops the Web proxy service.

Properties

The following table lists the properties of the FPCServer object.

Property | Description
Adapters | Gets a collection of objects representing the available network adapter cards (NICs).
CacheDrives | Getsa collection of cache drive objects in this server.
CreatedTime | Getsa DATE data type that specifies the creation time of the object.
CurrentDCName | Gets the name of the current domain controller.
Description | Gets or sets the description of the server.
DialupNetworkConnections | Getsa collection of dialup network connections in this server.
DiskDrives | Getsa collection of disk drive objects in this server.
FirewallServiceStatus | Getswhether the Firewall service is running on the server.
FirewallServiceUpTime | Getsa value indicating the number of seconds that the Firewall service has been working properly.
FirewallSessions | Getsa collection of Firewall session objects on this server.
FirewallSessionsCount | Gets the number of Firewall sessions running on the server.
ForwardProxyListenEntries | Getsa collection of FPCListenEntry objects.
FQDN | Getsthe Fully Qualified Domain Name (FQDN) of the server.
HttpViaHeaderAlias | Gets or sets the HttpViaHeaderAlias setting of the server, which the Web proxy adds to each HTTP response from this server.
InstallationDirectory | Gets the ISA installation directory.
IntraArrayAddress | Gets or setsa reference to the returned key string.
LastModifiedTime | Getsa DATE data type that specifies the last modification time of the object.
LoadFactor | Gets or sets the load factor for the server.
Name | Getsthe name of the server.
ProductID | Getsthe identifier (ID) of the product installed on this server.
ProductVersion | Getsthe version of the server.
ReverseProxyListenEntries | Returns a collection of FPCListenEntry objects.
ScheduledContentDownloadServiceStatus | Returns a Boolean value indicating the status of the scheduled content download service.
ServerStatus | Indicates whether the server is connectable.
SignaledAlerts | Returns a reference to the FPCSignaledAlerts collection.
SSLClientCertificates | Returns an FPCSSLCertificates collection that represents SSL client certificates available on the server.
SSLServerCertificates | Returns an FPCSSLCertificates collection representing SSL server certificates available on the server.
VendorParametersSets | Returns a reference to an object for storing and loading custom data into the FPCServer object's storage.
WebProxyServiceStatus | Returns a Boolean value indicating whether the Web proxy is running.
WebProxyServiceUpTime | Returns a value indicating the number of seconds that the Web proxy service has been working properly.
WebProxySessionsCount | Gets the number of Web proxy sessions running on the server.
WebSessions | Returns a collection of Web session objects in this server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCServer.Adapters Property

Gets a collection of objects representing the available network adapter cards (NICs).

VBScript Syntax[VBScript]

[ collFPCAdapters = ] FPCServer.Adapters

C++ Syntax[C++]

HRESULT get_Adapters(
  IFPCAdapters **pcollFPCAdapters
);

Parameters

collFPCAdapters
Reference to the FPCAdapters collection.

The property is read-only.


FPCServer.CacheDrives Property

Gets a collection of cache drive objects in this server.

VBScript Syntax[VBScript]

[ collFPCCacheDrives = ] FPCServer.CacheDrives

C++ Syntax[C++]

HRESULT get_CacheDrives(
  IFPCCacheDrives **pcollFPCCacheDrives
);

Parameters

collFPCCacheDrives
Reference to the FPCCacheDrives collection.

The property is read-only.

Applies To

FPCServer


FPCServer.CreatedTime Property

Gets a DATE data type that specifies the creation time of the object.

VBScript Syntax[VBScript]

[ dCreatedTime = ] FPCServer.CreatedTime

C++ Syntax[C++]

HRESULT get_CreatedTime(
  DATE *pdCreatedTime
);

Parameters

dCreatedTime
Reference to a DATE data type that specifies the creation time of the object.

The property is read-only.

Applies To

FPCServer


FPCServer.CurrentDCName Property

Gets the name of the current domain controller.

VBScript Syntax[VBScript]

[ sDCName = ] FPCServer.CurrentDCName

C++ Syntax[C++]

HRESULT get_CurrentDCName(
  BSTR *psDCName
);

Parameters

sDCName
String that specifies the name of the domain controller.

The property is read-only.

Applies To

FPCServer


FPCServer.Description Property

Gets or sets the description of the server.

VBScript Syntax[VBScript]

FPCServer.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the server.

The property is read-write.

Applies To

FPCServer


FPCServer.DialupNetworkConnections Property

Gets a collection of dialup network connections in this server.

VBScript Syntax[VBScript]

[ oFPCDialupNetworkConnections = ] FPCServer.DialupNetworkConnections

C++ Syntax[C++]

HRESULT get_DialupNetworkConnections(
  IFPCDialupNetworkConnections **poFPCDialupNetworkConnections
);

Parameters

oFPCDialupNetworkConnections
Reference to the FPCDialupNetworkConnections collection.

The property is read-only.

Applies To

FPCServer


FPCServer.DiskDrives Property

Gets a collection of disk-drive objects in this server.

VBScript Syntax[VBScript]

[ collFPCDiskDrives = ] FPCServer.DiskDrives

C++ Syntax[C++]

HRESULT get_DiskDrives(
  IFPCDiskDrives **pcollFPCDiskDrives
);

Parameters

collFPCDiskDrives
Reference to the FPCDiskDrives collection.

The property is read-only.

Applies To

FPCServer


FPCServer.FirewallServiceStatus Property

Gets a Boolean value that indicates whether the Firewall service is running.

VBScript Syntax[VBScript]

[ bFirewallServiceStatus = ] FPCServer.FirewallServiceStatus

C++ Syntax[C++]

HRESULT get_FirewallServiceStatus(
  VARIANT_BOOL *pbFirewallServiceStatus
);

Parameters

bFirewallServiceStatus
Boolean value indicating whether the Firewall service is running.

The property is read-only.

Applies To

FPCServer


FPCServer.FirewallServiceUpTime Property

Gets a value indicating the number of seconds that the Firewall service has worked properly.

VBScript Syntax[VBScript]

[ lSeconds = ] FPCServer.FirewallServiceUpTime

C++ Syntax[C++]

HRESULT get_FirewallServiceUpTime(
  LONG *plSeconds
);

Parameters

lSeconds
Long value that indicates the number of seconds that the Firewall service has worked properly.

The property is read-only.

Applies To

FPCServer


FPCServer.FirewallSessions Property

Gets a collection of FPCFirewallSession objects in this server.

VBScript Syntax[VBScript]

[ collFPCFirewallSessions = ] FPCServer.FirewallSessions

C++ Syntax[C++]

HRESULT get_FirewallSessions(
  IFPCFirewallSessions **pcollFPCFirewallSessions
);

Parameters

collFPCFirewallSessions
Reference to the FPCFirewallSessions collection.

The property is read-only.

Applies To

FPCServer


FPCServer.FirewallSessionsCount Property

Gets the number of Firewall sessions running on this server.

VBScript Syntax[VBScript]

[ lCount = ] FPCServer.FirewallSessionsCount

C++ Syntax[C++]

HRESULT get_FirewallSessionsCount(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of Firewall sessions running on the server.

The property is read-only.

Applies To

FPCServer


FPCServer.ForwardProxyListenEntries Property

Gets a collection of FPCListenEntry objects.

Note If there are no listen entries configured using the FPCListenEntries.Add method, then ISA does not listen for incoming or outgoing Web requests.

VBScript Syntax[VBScript]

[ collFPCListenEntries = ] FPCServer.ForwardProxyListenEntries

C++ Syntax[C++]

HRESULT get_ForwardProxyListenEntries(
  IFPCListenEntries **pcollFPCListenEntries
);

Parameters

collFPCListenEntries
Reference to the FPCListenEntries collection.

The property is read-only.

Applies To

FPCServer


FPCServer.FQDN Property

Gets the Fully Qualified Domain Name (FQDN) of the server.

VBScript Syntax[VBScript]

[ sFQDN = ] FPCServer.FQDN

C++ Syntax[C++]

HRESULT get_FQDN(
  BSTR *psFQDN
);

Parameters

sFQDN
String that specifies the FQDN.

The property is read-only.

Applies To

FPCServer


FPCServer.HttpViaHeaderAlias Property

Gets or sets the HttpViaHeaderAlias setting of the server, which the Web proxy adds to each HTTP response from this server.

VBScript Syntax[VBScript]

FPCServer.HttpViaHeaderAlias [ = sViaHeaderAlias ]

C++ Syntax[C++]

HRESULT get_HttpViaHeaderAlias(
  BSTR *psViaHeaderAlias
);

HRESULT put_HttpViaHeaderAlias(
  BSTR sViaHeaderAlias
);

Parameters

sViaHeaderAlias
String that specifies the via-header property of the server.

The property is read-write.

Applies To

FPCServer


FPCServer.InstallationDirectory Property

Gets the ISA installation directory.

VBScript Syntax[VBScript]

[ sInstallationDirectory = ] FPCServer.InstallationDirectory

C++ Syntax[C++]

HRESULT get_InstallationDirectory(
  BSTR *psInstallationDirectory
);

Parameters

sInstallationDirectory
String that specifies the ISA installation directory.

The property is read-only.

Applies To

FPCServer


FPCServer.IntraArrayAddress Property

Gets or sets a reference to the returned key string. The key string is the IP address for communication between array members, when routing requests for CARP. Each server must have an IP address defined to serve as the intra-array address.

Note For CARP to function for incoming Web requests, be sure that the IP address that is used for intra-array communication (by default, an internal IP address) listens for requests on the same port as the IP address configured to listen for incoming Web requests. The default port is port 80.

To do this, configure the array's incoming Web request properties to use the same listener configuration for all IP addresses, by using the FPCWebRequestConfiguration.AllInterfaces property. Alternatively, you can add the IP address used for intra-array communication to the list of incoming Web request listeners by using the FPCListenEntry.IP property.

VBScript Syntax[VBScript]

FPCServer.IntraArrayAddress [ = sIntraArrayAddress ]

C++ Syntax[C++]

HRESULT get_IntraArrayAddress(
  BSTR *psIntraArrayAddress
);

HRESULT put_IntraArrayAddress(
  BSTR sIntraArrayAddress
);

Parameters

sIntraArrayAddress
Reference to returned key string.

The property is read-write.

Applies To

FPCServer


FPCServer.LastModifiedTime Property

Gets a DATE data type that specifies the last modification time of the object.

VBScript Syntax[VBScript]

[ dLastModifiedTime = ] FPCServer.LastModifiedTime

C++ Syntax[C++]

HRESULT get_LastModifiedTime(
  DATE *pdLastModifiedTime
);

Parameters

dLastModifiedTime
Reference to a DATE data type.

The property is read-only.

Applies To

FPCServer


FPCServer.LoadFactor Property

Gets or sets the load factor of the server. A load factor is a relative number that assigns more traffic to servers that are able to handle more requests.

VBScript Syntax[VBScript]

FPCServer.LoadFactor [ = lLoadFactor ]

C++ Syntax[C++]

HRESULT get_LoadFactor(
  long *plLoadFactor
);

HRESULT put_LoadFactor(
  long lLoadFactor
);

Parameters

lLoadFactor
Long value that specifies the load factor.

The property is read-write.

Applies To

FPCServer


FPCServer.Name Property

Gets the name of the server.

VBScript Syntax[VBScript]

[ sName = ] FPCServer.Name

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

Parameters

sName
String that specifies the server name.

The property is read-only.

Applies To

FPCServer


FPCServer.ProductId Property

Gets the identifier (ID) of the product installed on this server.

VBScript Syntax[VBScript]

[ sProductId = ] FPCServer.ProductId

C++ Syntax[C++]

HRESULT get_ProductId(
  BSTR *psProductId
);

Parameters

sProductId
String that specifies the product ID.

The property is read-only.

Applies To

FPCServer


FPCServer.ProductVersion Property

Gets the version of the server.

VBScript Syntax[VBScript]

[ sVersion = ] FPCServer.ProductVersion

C++ Syntax[C++]

HRESULT get_ProductVersion(
  BSTR *psVersion
);

Parameters

sVersion
String that specifies the version of the server.

The property is read-only.

Applies To

FPCServer


FPCServer.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCServer.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCServer


FPCServer.RestartServices Method

Gets a collection of services that were previously stopped by the StopAllServices method and restarts those services.

VBScript Syntax[VBScript]

[ vServices = ] FPCServer.RestartServices()

C++ Syntax[C++]

HRESULT RestartServices(
  VARIANT *vServices
);

Parameters

vServices
Variant that specifies the names of the services.

Applies To

FPCServer


FPCServer.ReverseProxyListenEntries Property

Gets a collection of FPCListenEntry objects.

Note If there are no listen entries configured using the FPCListenEntries.Add method, then ISA does not listen for incoming or outgoing Web requests.

VBScript Syntax[VBScript]

[ collFPCListenEntries = ] FPCServer.ReverseProxyListenEntries

C++ Syntax[C++]

HRESULT get_ReverseProxyListenEntries(
  IFPCListenEntries **pcollFPCListenEntries
);

Parameters

collFPCListenEntries
Reference to the FPCListenEntries collection.

The property is read-only.

Applies To

FPCServer


FPCServer.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCServer.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCServer


FPCServer.ScheduledContentDownloadServiceStatus Property

Gets a Boolean value that indicates whether the status scheduled content download service is running.

VBScript Syntax[VBScript]

[ bStatus = ] FPCServer.ScheduledContentDownloadServiceStatus

C++ Syntax[C++]

HRESULT get_ScheduledContentDownloadServiceStatus(
  VARIANT_BOOL *pbStatus
);

Parameters

bStatus
A Boolean value that indicates whether the scheduled content download service.

The property is read-only.

Applies To

FPCServer


FPCServer.ServerStatus Property

Gets a Boolean value indicating whether the server is functioning.

VBScript Syntax[VBScript]

[ bServerStatus = ] FPCServer.ServerStatus

C++ Syntax[C++]

HRESULT get_ServerStatus(
  VARIANT_BOOL *pbServerStatus
);

Parameters

bServerStatus
Boolean value indicating whether the server is functioning.

The property is read-only.

Applies To

FPCServer


FPCServer.SignaledAlerts Property

Gets a reference to the FPCSignaledAlerts collection.

VBScript Syntax[VBScript]

[ collFPCSignaledAlerts = ] FPCServer.SignaledAlerts

C++ Syntax[C++]

HRESULT get_SignaledAlerts(
  IFPCSignaledAlerts **pcollFPCSignaledAlerts
);

Parameters

collFPCSignaledAlerts
A reference to the FPCSignaledAlerts collection.

The property is read-only.

Applies To

FPCServer


FPCServer.SSLClientCertificates Property

Gets an FPCSSLCertificates collection that represents Secure Sockets Layer (SSL) client certificates available on the server.

VBScript Syntax[VBScript]

[ collFPCSSLCertificates = ] FPCServer.SSLClientCertificates

C++ Syntax[C++]

HRESULT get_SSLClientCertificates(
  IFPCSSLCertificates **pcollFPCSSLCertificates
);

Parameters

collFPCSSLCertificates
Reference to an FPCSSLCertificates collection representing SSL client certificates available on the server.

The property is read-only.


FPCServer.SSLServerCertificates Property

Gets an FPCSSLCertificates collection representing Secure Sockets Layer (SSL) server certificates available on the server.

VBScript Syntax[VBScript]

[ collFPCSSLCertificates = ] FPCServer.SSLServerCertificates

C++ Syntax[C++]

HRESULT get_SSLServerCertificates(
  IFPCSSLCertificates **pcollFPCSSLCertificates
);

Parameters

collFPCSSLCertificates
Reference to an FPCSSLCertificates collection representing SSL server certificates available on the server.

The property is read-only.


FPCServer.StartFirewallService Method

Starts the Firewall service.

VBScript Syntax[VBScript]

FPCServer.StartFirewallService( fWaitUntilComplete )

C++ Syntax[C++]

HRESULT StartFirewallService(
  VARIANT_BOOL fWaitUntilComplete
);

Parameters

fWaitUntilComplete
Boolean that specifies whether the method waits for the operation to complete before the method returns S_OK or an error.

Applies To

FPCServer

See Also

FPCServer.StopFirewallService


FPCServer.StartScheduledContentDownloadService Method

Starts the scheduled content download service.

VBScript Syntax[VBScript]

FPCServer.StartScheduledContentDownloadService( fWaitUntilComplete )

C++ Syntax[C++]

HRESULT StartScheduledContentDownloadService(
  VARIANT_BOOL fWaitUntilComplete
);

Parameters

fWaitUntilComplete
Boolean that specifies whether the method waits for the operation to complete before the method returns S_OK or an error.

Applies To

FPCServer

See Also

FPCServer.StopScheduledContentDownloadService


FPCServer.StartWebProxyService Method

Starts the Web proxy service.

VBScript Syntax[VBScript]

FPCServer.StartWebProxyService( fWaitUntilComplete )

C++ Syntax[C++]

HRESULT StartWebProxyService(
  VARIANT_BOOL fWaitUntilComplete
);

Parameters

fWaitUntilComplete
Boolean that specifies whether the method waits for the operation to complete before the method returns S_OK or an error.

Applies To

FPCServer

See Also

FPCServer.StopWebProxyService


FPCServer.StopAllServices Method

Stops all the running ISA services, and the services that depend on those ISA services, on the current server, then returns a collection of the services that were stopped.

VBScript Syntax[VBScript]

[ vServices = ] FPCServer.StopAllServices()

C++ Syntax[C++]

HRESULT StopAllServices(
  VARIANT *pvServices
);

Parameters

vServices
Variant that specifies the names of the services.

Applies To

FPCServer


FPCServer.StopFirewallService Method

Stops the Firewall service.

VBScript Syntax[VBScript]

FPCServer.StopFirewallService( fWaitUntilComplete )

C++ Syntax[C++]

HRESULT StopFirewallService(
  VARIANT_BOOL fWaitUntilComplete
);

Parameters

fWaitUntilComplete
Boolean that specifies whether the method waits for the operation to complete before the method returns S_OK or an error.

Applies To

FPCServer

See Also

FPCServer.StartFirewallService


FPCServer.StopScheduledContentDownloadService Method

Stops the scheduled content download service.

VBScript Syntax[VBScript]

FPCServer.StopScheduledContentDownloadService( fWaitUntilComplete )

C++ Syntax[C++]

HRESULT StopScheduledContentDownloadService(
  VARIANT_BOOL fWaitUntilComplete
);

Parameters

fWaitUntilComplete
Boolean that specifies whether the method waits for the operation to complete before the method returns S_OK or an error.

Applies To

FPCServer

See Also

FPCServer.StartScheduledContentDownloadService


FPCServer.StopWebProxyService Method

Stops the Web proxy service.

VBScript Syntax[VBScript]

FPCServer.StopWebProxyService( fWaitUntilComplete )

C++ Syntax[C++]

HRESULT StopWebProxyService(
  VARIANT_BOOL fWaitUntilComplete
);

Parameters

fWaitUntilComplete
Boolean that specifies whether the method waits for the operation to complete before the method returns S_OK or an error.

Parameters

fWaitUntilComplete
Optional.

Applies To

FPCServer

See Also

FPCServer.StartWebProxyService


FPCServer.VendorParametersSets Property

Returns a reference to an object for storing and loading custom data into the FPCServer object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCServer.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCServer


FPCServer.WebProxyServiceStatus Property

Gets a Boolean value that indicates whether the Web proxy is running.

VBScript Syntax[VBScript]

[ bWebProxyServiceStatus = ] FPCServer.WebProxyServiceStatus

C++ Syntax[C++]

HRESULT get_WebProxyServiceStatus(
  VARIANT_BOOL *pbWebProxyServiceStatus
);

Parameters

bWebProxyServiceStatus
Boolean value indicating whether the Web proxy is running.

The property is read-only.

Applies To

FPCServer


FPCServer.WebProxyServiceUpTime Property

Gets a value indicating the number of seconds that the Web proxy service has worked properly.

VBScript Syntax[VBScript]

[ lSeconds = ] FPCServer.WebProxyServiceUpTime

C++ Syntax[C++]

HRESULT get_WebProxyServiceUpTime(
  LONG *plSeconds
);

Parameters

lSeconds
Long value indicating the number of seconds that the Web proxy service has worked properly.

The property is read-only.

Applies To

FPCServer


FPCServer.WebProxySessionsCount Property

Gets the number of Web proxy sessions running on this server.

VBScript Syntax[VBScript]

[ lCount = ] FPCServer.WebProxySessionsCount

C++ Syntax[C++]

HRESULT get_WebProxySessionsCount(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of Web proxy sessions running on the server.

The property is read-only.

Applies To

FPCServer


FPCServer.WebSessions Property

Gets a collection of FPCWebSession objects in this server.

VBScript Syntax[VBScript]

[ collFPCWebSessions = ] FPCServer.WebSessions

C++ Syntax[C++]

HRESULT get_WebSessions(
  IFPCWebSessions **pcollFPCWebSessions
);

Parameters

collFPCWebSessions
Reference to the FPCWebSessions collection.

The property is read-only.

Applies To

FPCServer


FPCServers Collection

The FPCServers collection holds a group of FPCServer objects. This collection represents all the servers within the current array. All configurable settings within each ISA Server computer can be accessed by using objects within this collection.

It is a property of the FPCArray object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCServers interface.

Methods

The following table lists the methods of the FPCServers collection.

Method | Description
GetContainingServer | Returns the server containing the current computer.
Item | Retrieves the given FPCServer object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a server from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCServers collection

Property | Description
Count | Gets the number of server objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCServers collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCServers.Count Property

Gets the number of server objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCServers.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCServer objects.

The property is read-only.

Applies To

FPCServers


FPCServers.GetContainingServer Method

Returns the server containing the current computer.

VBScript Syntax[VBScript]

[ oFPCServer = ] FPCServers.GetContainingServer()

C++ Syntax[C++]

HRESULT GetContainingServer(
  IFPCServer **poFPCServer
);

Return Values

oFPCServer
Reference to the server that contains the current computer.

Example

The following Visual Basic code retrieves the name of the containing ISA server by means of the GetContainingServer method.

Dim objFPC As New FPCLib.FPC
Dim ContainingServer As String
Dim objFPCArrays As FPCArrays
Dim objFPCArray As FPCArray
Dim objFPCServer As FPCServers
Set objFPCArrays = objFPC.Arrays
Set objFPCArray = objFPCArrays.GetContainingArray
Set objFPCServers = objFPCArray.Servers
ContainingServer = objFPCServers.GetContainingServer.Name

Applies To

FPCServers


FPCServers.Item Method

Returns the given FPCServer object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCServers.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCServer **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
If successful, returns a reference to an object of type FPCServer, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCServers


FPCServers.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCServers.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCServers


FPCServers.Remove Method

Removes a server from the collection.

Note This method is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

VBScript Syntax[VBScript]

FPCServers.Remove( vIndex, bForced )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex,
  VARIANT_BOOL bForced
);

Parameters

vIndex
Required. Name or one-based index of the FPCServer object to remove.
bForced
Optional. Boolean value that indicates whether the removal of the server will be forced. The default value is FALSE, indicating that if a packet filter or alert is associated with the particular server, the server will not be removed. If you set this value to TRUE, then even if a packet filter or alert is associated with the server, the server will be removed, as will be that alert or packet filter.

Remarks

The FPCServers collection represents a server array; you remove a server from an array by using the Remove method. This removal is not permanent until after the Save method is called and the new array contents are saved to persistent storage.

Applies To

FPCServers


FPCServers.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCServers.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCServers


FPCServers.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCServers collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCServers.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCServers


FPCServerPublishingRule Object

Server publishing processes incoming requests to internal servers, such as Simple Mail Transfer Protocol (SMTP) servers, File Transfer Protocol (FTP) servers, Structured Query Language (SQL) servers, and others. Requests are forwarded downstream to an internal server, located behind the ISA Server computer. Server publishing rules determine how server publishing functions, essentially filtering all incoming and outgoing requests through the ISA Server computer.

A server publishing rule uses Secure Network Address Translation (SecureNAT), that substitutes a global IP address, which is valid on the Internet, for an internal IP address. The FPCServerPublishingRule object maps an external Internet Protocol (IP) address and a port slot on an ISA computer to an internal IP address. Requests received on the external IP address will be redirected to the internal IP address. Only requests that are identified as part of the designated protocol will be redirected to the internal server.

Publishing rules cannot be created at the enterprise level. However, the enterprise administrator can specify, by using the FPCEnterprise.AllowPublishing property, whether an array is allowed to publish servers. If the array is allowed to publish, the array administrator can create Web publishing rules (FPCWebPublishingRule object) or server publishing rules (FPCServerPublishingRule object). If the enterprise policy does not allow publishing, then an attempt to add a Web or server publishing rule will return an error message.

This object is a member of the FPCServerPublishingRules collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCServerPublishingRule interface.

Methods

The following table lists the methods of the FPCServerPublishingRule object.

Method | Description
GetPrimaryPortOfProtocolUsed | Returns the primary port associated with the protocol that was set in the call to the SetProtocol method.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetProtocol | Sets the protocol for the rule.

Properties

The following table lists the properties of the FPCServerPublishingRule object.

Property | Description
AppliesToMethod | Gets or sets the entity to which the rule applies.
ClientAddressSetsExcluded | Gets the excluded client address sets.
ClientAddressSetsUsed | Gets the client address sets used.
Description | Gets or sets the description of the rule.
Enabled | Gets or sets whether the rule is enabled.
ExternalIp | Gets or sets the external address to which the specified internal addresses are mapped.
InternalIp | Gets or sets the internal address to which the requests on the external IP will be redirected.
Name | Gets or sets the name of the rule.
ProtocolUsed | Gets the protocol used by the rule.
VendorParametersSets | Retrieves a reference to an object for storing and loading custom data into the FPCServerPublishingRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCServerPublishingRule.AppliesToMethod Property

Gets or sets the method used for deciding the applicability of SecureNAT mapping.

VBScript Syntax[VBScript]

FPCServerPublishingRule.AppliesToMethod [ = AppliesToType]

C++ Syntax[C++]

HRESULT get_AppliesToMethod(
  FpcAppliesToType *pAppliesToType
);

HRESULT put_AppliesToMethod(
  FpcAppliesToType AppliesToType
);

Parameters

AppliesToType
Applicability method. It can have a value from the FpcAppliesToType enumerated type.

The property is read-write.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.ClientAddressSetsExcluded Property

Gets the client address sets excluded from the server publishing. This property is useful only when the ClientSetsUsed property is not empty. It allows you to design a server publishing rule that applies to one set of clients but excludes another set of clients.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCServerPublishingRule.ClientAddressSetsExcluded

C++ Syntax[C++]

HRESULT get_ClientAddressSetsExcluded(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
The FPCRefs collection used to define the client address sets.

The property is read only.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.ClientAddressSetsUsed Property

Gets the client address sets used in the server publishing.

The server publishing rule is applied to client address sets only if IP packet filtering is enabled. If IP packet filtering is not enabled, then the server publishing rule applies to all clients.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCServerPublishingRule.ClientAddressSetsUsed

C++ Syntax[C++]

HRESULT get_ClientAddressSetsUsed(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
The FPCRefs collection used to define the client address sets.

The property is read only.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.Description Property

Gets or sets the description of the server publishing rule. The description is stored as a string.

VBScript Syntax[VBScript]

FPCServerPublishingRule.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the rule.

The property is read-write.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.Enabled Property

Gets or sets whether the rule is enabled.

VBScript Syntax[VBScript]

FPCServerPublishingRule.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
A Boolean value that specifies whether a rule is enabled.

The property is read-write.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.ExternalIp Property

Gets or sets the external Internet Protocol (IP) address of one of the ISA servers in the array, to which the specified internal addresses are mapped. An external address is one that is not in the Local Address Table (LAT).

Note If the address provided is not that of an external IP, an error will be returned.

VBScript Syntax[VBScript]

FPCServerPublishingRule.ExternalIp [ = sExternalIP ]

C++ Syntax[C++]

HRESULT get_ExternalIp(
  BSTR *psExternalIP
);

HRESULT put_ExternalIp(
  BSTR sExternalIP
);

Parameters

sExternalIP
String that specifies the external IP.

The property is read-write.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.GetPrimaryPortOfProtocolUsed Method

Returns the primary port associated with the protocol that was set in the call to SetProtocol.

VBScript Syntax[VBScript]

[ lPort = ] FPCServerPublishingRule.GetPrimaryPortOfProtocolUsed

C++ Syntax[C++]

HRESULT GetPrimaryPortOfProtocolUsed(
 long *plPort
);

Parameters

lPort
Long value that specifies the port number.

See Also

FPCServerPublishingRule


FPCServerPublishingRule.InternalIp Property

Gets or sets the internal IP address for the publishing server. This would be the address of the internal server you want to publish.

VBScript Syntax[VBScript]

FPCServerPublishingRule.InternalIp [ = sInternalIp ]

C++ Syntax[C++]

HRESULT get_InternalIp(
  BSTR *psInternalIp
);

HRESULT put_InternalIp(
  BSTR sInternalIp
);

Parameters

sInternalIp
String that specifies the internal IP.

The property is read-write.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.Name Property

Gets or sets the name of the rule. The name of the rule is stored as a string.

VBScript Syntax[VBScript]

FPCServerPublishingRule.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the rule name.

The property is read-write.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.ProtocolUsed Property

Gets a FPCRef object that represents the protocol used by the server publishing rule. Set the protocol by using the SetProtocol method.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCServerPublishingRule.ProtocolUsed

C++ Syntax[C++]

HRESULT get_ProtocolUsed(
  IFPCRef **poFPCRef
);

Parameters

oFPCRef
An FPCRef object that specifies the protocol.

The property is read-only.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCServerPublishingRule.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCServerPublishingRule.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.SetProtocol Method

Sets the protocol for the server publishing rule. Note that for the operation to succeed, the protocol must be a server protocol, which has an inbound primary connection.

VBScript Syntax[VBScript]

FPCServerPublishingRule.SetProtocol( sProtocolName, sApplicationFilterGuid, FpcItemScope )

C++ Syntax[C++]

HRESULT SetProtocol(
  BSTR sProtocolName,
  BSTR sApplicationFilterGuid,
  FpcItemScope FpcItemScope
);

Parameters

sProtocolName
Required. String that specifies the name of the protocol.
sApplicationFilterGuid
Optional. String that specifies the GUID of the application filter if this is an application filter protocol. The default value is an empty string.
FpcItemScope
Optional. Value from the FpcItemScope enumerated type. Specifies whether the protocol is taken from the enterprise list of protocols or the local array list of protocols. The default value is fpcArrayScope. This parameter is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

Applies To

FPCServerPublishingRule


FPCServerPublishingRule.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCServerPublishingRule object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCServerPublishingRule.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCServerPublishingRule


FPCServerPublishingRules Collection

The FPCServerPublishingRules collection provides access to a group of FPCServerPublishingRule objects. This object is a property of the FPCPublishing object.

Click here to see the ISA object hierarchy.

to C++ Programmers

This collection implements the IFPCServerPublishingRules interface.

Methods

The following table lists the methods of the FPCServerPublishingRules collection.

Method | Description
Add | Creates a new FPCServerPublishingRule object.
Item | Retrieves the given object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCServerPublishingRule object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCServerPublishingRules collection.

Property | Description
Count | Gets the number of objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCServerPublishingRules.Add Method

Creates a new FPCServerPublishingRule object in the collection and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCServerPublishingRule = ] FPCServerPublishingRules.Add( sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  IFPCServerPublishingRule **ppoFPCServerPublishingRule
);

Parameters

sName
String that specifies the new FPCServerPublishingRule object to add.

Return Values

oFPCServerPublishingRule
Returns a reference to the new FPCServerPublishingRule object.

Applies To

FPCServerPublishingRules


FPCServerPublishingRules.Count Property

Gets the number of content groups objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCServerPublishingRules.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of destination set objects.

The property is read-only.

Applies To

FPCServerPublishingRules


FPCServerPublishingRules.Item Method

Retrieves the given FPCServerPublishingRule object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCServerPublishingRules.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCServerPublishingRule **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

vItem
Variant. Returns an object if successful; otherwise NULL .

Applies To

FPCServerPublishingRules


FPCServerPublishingRules.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCServerPublishingRules.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCServerPublishingRules


FPCServerPublishingRules.Remove Method

Removes a content group set object from the collection.

VBScript Syntax[VBScript]

FPCServerPublishingRules.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCServerPublishingRules


FPCServerPublishingRules.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCServerPublishingRules.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCServerPublishingRules


FPCServerPublishingRules.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCServerPublishingRules collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCServerPublishingRules.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCServerPublishingRules


FPCSignaledAlert Object

The FPCSignaledAlert object represents a single signaled alert. This object is a member of the FPCSignaledAlerts collection.

The FPCSignaledAlert object is a run-time instance of an FPCAlert object. Signaled alerts appear under Real Time Monitoring in ISA Management, and ISA alerts appear under Monitoring Configuration. An FPCAlert object contains alert configuration information, while the FPCSignaledAlert object contains both configuration and run-time information.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCSignaledAlert interface.

Methods

The following table lists the methods of the FPCSignaledAlert object.

Method | Description
Refresh | Reads the FPCSignaledAlert objects by means of a remote procedure call (RPC).
Reset | Resets the alert.

Properties

The following table lists the properties of the FPCSignaledAlert object.

Property | Description
ActiveSince | Gets a DATE value that specifies the date since the alert has been active.
AdditionalKey | Gets the additional key of the alert.
Description | Gets the description of the alert.
EventGuid | Gets the event.
Name | Gets the name of the signaled alert.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSignaledAlert.ActiveSince Property

Gets a DATE value that specifies the date and Greenwich Mean Time (GMT) from which the alert has been active.

VBScript Syntax[VBScript]

[ dActiveSince = ] FPCSignaledAlert.ActiveSince

C++ Syntax[C++]

HRESULT get_ActiveSince(
  DATE *pdActiveSince
);

Parameters

dActiveSince
DATE value that specifies the date since the alert has been active.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.AdditionalKey Property

Gets the additional key of the alert.

VBScript Syntax[VBScript]

[ lAdditionalKey = ] FPCSignaledAlert.AdditionalKey

C++ Syntax[C++]

HRESULT get_AdditionalKey(
  long *plAdditionalKey
);

Parameters

lAdditionalKey
Long value that specifies the index of the additional key.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.Description Property

Gets the description of the alert.

VBScript Syntax[VBScript]

[ sDescription = ] FPCSignaledAlert.Description

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

Parameters

sDescription
String that specifies the description of the alert.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.EventGuid Property

Gets the event that triggered the alert.

VBScript Syntax[VBScript]

[ sGuid = ] FPCSignaledAlert.EventGuid

C++ Syntax[C++]

HRESULT get_EventGUID(
  BSTR *psGuid
);

Parameters

sGuid
String that specifies the event globally unique identifier (GUID).

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.Name Property

Gets the name of the signaled alert.

VBScript Syntax[VBScript]

[ sName = ] FPCSignaledAlert.Name

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

Parameters

sName
String that specifies the name of the signaled alert.

The property is read-only.

Applies To

FPCSignaledAlert


FPCSignaledAlert.Refresh Method

Reads all the properties by means of a remote procedure call (RPC).

VBScript Syntax[VBScript]

FPCSignaledAlert.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCSignaledAlert


FPCSignaledAlert.Reset Method

Resets the alert. This clears all counts held by the alert service, putting the alert back in an alertable state. The next signal will then cause the alert to be invoked.

VBScript Syntax[VBScript]

FPCSignaledAlert.Reset()

C++ Syntax[C++]

HRESULT Reset();

Applies To

FPCSignaledAlert


FPCSignaledAlerts Collection

The FPCSignaledAlerts collection provides access to a group of FPCSignaledAlert objects. This object is a property of the FPCServer object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCSignaledAlerts interface.

Methods

The following table lists the methods of the FPCSignaledAlerts collection.

Method | Description
Item | Retrieves the given FPCSignaledAlert object from the collection.
Refresh | Reads all the FPCSignaledAlert objects using remote procedure calls (RPCs).

Properties

The following table lists the properties of the FPCSignaledAlerts collection.

Property | Description
Count | Gets the number of FPCSignaledAlert objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSignaledAlerts.Count Property

Gets the number of FPCSignaledAlert objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCSignaledAlerts.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCSignaledAlert objects.

The property is read-only.

Applies To

FPCSignaledAlerts


FPCSignaledAlerts.Item Method

Retrieves the given FPCSignaledAlert object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCSignaledAlerts.Item( vIndexOrEventGuid, vAdditionalKey )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndexOrEventGuid,
  VARIANT vAdditionalKey,
  IFPCSignaledAlert **pvItem
);

Parameters

vIndexOrEventGuid
Required. Event globally unique identifier (GUID) or one-based index of the object to retrieve.
vAdditionalKey
Required if vIndex contains an event GUID, optional if vIndex contains one-based index. See FPCAlert.AdditionalKey.

Return Value

vItem
If successful, returns a reference to an object of type FPCSignaledAlert, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCSignaledAlerts


FPCSignaledAlerts.Refresh Method

Reads all the FPCSignaledAlert objects by means of a remote procedure call (RPC).

VBScript Syntax[VBScript]

FPCSignaledAlerts.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCSignaledAlerts


FPCSiteAndContentRule Object

The FPCSiteAndContentRule object represents a site and content rule. A site and content rule defines actions that will be taken when specific users attempt to access specific sites or content by using ISA. ISA site and content rules allow you to define exactly which sites and content can be accessed by clients behind the ISA server. Site and content rules also determine when the rule is in effect by applying the rule during a specific schedule.

Site and content rules can be created at both the array level and at the enterprise level. When an array policy is allowed, then its site and content rules can only further restrict enterprise-level site and content rules. For more information about enterprise nad array policy, see Enterprise and Array Policy.

This object is a member of the FPCSiteAndContentRules collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCSiteAndContentRule interface.

Methods

The following table lists the methods of the FPCSiteAndContentRule object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetAppliesAlways | Sets the rule to apply always regardless of the ScheduleUsed property.
SetDestination | Sets the destinations to which the rule applies.
SetSchedule | Sets the schedule to which the rule applies.

Properties

The following table lists the properties of the FPCSiteAndContentRule object.

Property | Description
Action | Gets or sets the type of action that this rule performs.
AppliesAlways | Gets whether the rule applies at all times.
AppliesToAccounts | Gets the collection of accounts for which the rule applies.
AppliesToContentMethod | Gets or sets the type of content to which the rule applies.
AppliesToDestination | Gets the type of destination to which the rule applies.
AppliesToMethod | Gets or sets the method used for deciding rule applicability.
ClientAddressSetsExcluded | Gets the collection of client address sets to which the rule does not apply.
ClientAddressSetsUsed | Gets the collection of client address sets to which the rule applies.
ContentGroupsUsed | Gets the collection of content groups to which the rule applies.
Description | Gets or sets the description of the rule.
DestinationSetUsed | Gets the name of the FPCDestinationSet collection used to define the destination to which the rule applies.
Enabled | Gets or sets whether the rule is enabled.
Name | Gets or sets the name of the rule.
RedirectUrl | Gets or sets the URL to which to redirect requests when the Action property is set to the fpcRuleActionRedirect value of the FpcRuleActions enumerated type.
ScheduleUsed | Gets or sets the name of the FPCSchedule object used to define the times when the rule applies.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCSiteAndContentRule object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSiteAndContentRule.Action Property

Gets or sets the type of action that this rule performs. The action may be to permit the request, deny the request, or redirect the request.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.Action [ = RuleActions ]

C++ Syntax[C++]

HRESULT get_Action(
  FpcRuleActions *pRuleActions
);

HRESULT put_Action(
  FpcRuleActions RuleActions
);

Parameters

RuleActions
Type of action. It can have a value from the FPCRuleActions enumerated type.

The property is read-write.

Remarks

Because array policy can only be more restrictive than enterprise policy, you can only add array site and content rules that deny access to what is already allowed by the enterprise, or rules that redirect requests. If you try to create an allow (fpcRuleActionPermit) site and content rule, you will receive an error message, and the rule is not created.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesAlways Property

Gets whether the rule applies at all times.

VBScript Syntax[VBScript]

[ bApplies = ] FPCSiteAndContentRule.AppliesAlways

C++ Syntax[C++]

HRESULT get_AppliesAlways(
  VARIANT_BOOL *pbApplies
);

Parameters

bApplies
Boolean value that specifies whether a rule always applies.

The property is read-only. It can be set to TRUE by calling the SetAppliesAlways method. Choosing a schedule by calling SetSchedule will set it to FALSE.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToAccounts Property

Gets the collection of accounts to which the rule applies.

VBScript Syntax[VBScript]

[ collFPCAccounts = ] FPCSiteAndContentRule.AppliesToAccounts

C++ Syntax[C++]

HRESULT get_AppliesToAccounts(
  IFPCAccounts **pcollFPCAccounts
);

Parameters

collFPCAccounts
Reference to the FPCAccounts collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToContentMethod Property

Gets or sets the type of content to which the rule applies.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.AppliesToContentMethod [ = FpcAppliesToContentMethodType ]

C++ Syntax[C++]

HRESULT get_AppliesToContentMethod(
  FpcAppliesToContentMethodType *pFpcAppliesToContentMethodType
);

HRESULT put_AppliesToContentMethod(
  FpcAppliesToContentMethodType FpcAppliesToContentMethodType
);

Parameters

FpcAppliesToContentMethodType
Type of content to which the rule applies. It can have a value of fpcAppliesToAllContent or fpcAppliesToSpecifiedContent from the FpcAppliesToContentMethodType enumerated type.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToDestination Property

Gets the type of destination to which the rule applies, either all destinations, all internal destinations, all external destinations, destinations that are part of a specified set, or all destinations except those in the specified destination set.

VBScript Syntax[VBScript]

[ DestinationSelection = ] FPCSiteAndContentRule.AppliesToDestination

C++ Syntax[C++]

HRESULT get_AppliesToDestination(
  FpcDestinationSelection *pDestinationSelection
);

Parameters

DestinationSelection
Type of destination to which the rule applies. It can have a value from the FpcDestinationSelection enumerated type.

The property is read-only. It can be set through the method SetDestination.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.AppliesToMethod Property

Gets or sets the method used for deciding rule applicability.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.AppliesToMethod [ = AppliesToType ]

C++ Syntax[C++]

HRESULT get_AppliesToMethod(
  FpcAppliesToType *pAppliesToType
);

HRESULT put_AppliesToMethod(
  FpcAppliesToType AppliesToType
);

Parameters

AppliesToType
Applicability method. It can have a value from the FpcAppliesToType enumerated type.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ClientAddressSetsExcluded Property

Gets the collection of client address sets to which the rule does not apply. This property is useful only when the ClientSetsUsed property is not empty. It allows you to design a rule that applies to one set of clients, but excludes another set of clients.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCSiteAndContentRule.ClientAddressSetsExcluded

C++ Syntax[C++]

HRESULT get_ClientAddressSetsExcluded(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ClientAddressSetsUsed Property

Gets the collection of client address sets for which the rule applies.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCSiteAndContentRule.ClientAddressSetsUsed

C++ Syntax[C++]

HRESULT get_ClientAddressSetsUsed(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
A reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ContentGroupsUsed Property

Gets the collection of content groups to which the rule applies.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCSiteAndContentRule.ContentGroupsUsed

C++ Syntax[C++]

HRESULT get_ContentGroupsUsed(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
A reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Description Property

Gets or sets the description of the rule.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the rule.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.DestinationSetUsed Property

Gets the FPCRef object used to define the destination to which the rule applies.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCSiteAndContentRule.DestinationSetUsed

C++ Syntax[C++]

HRESULT get_DestinationSetUsed(
  IFPCRef **poFPCRef
);

Parameters

oFPCRef
Reference to an FPCRef object.

The property is read-only. It can be set by using the SetDestination method.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Enabled Property

Gets or sets whether the rule is enabled.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether a rule is enabled.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Name Property

Gets or sets the name of the rule.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name.

The property is read-write.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.RedirectUrl Property

Gets or sets the URL to redirect requests to when the Action property is set to the fpcRuleActionRedirect value of the FpcRuleActions enumerated type.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.RedirectUrl [ = sURL ]

C++ Syntax[C++]

HRESULT get_RedirectUrl(
  BSTR *psURL
);

HRESULT put_RedirectUrl(
  BSTR sURL
);

Parameters

sURL
String that specifies the URL.

The property is read-write.

Note If you choose to redirect the request, then the URL that you specify must be accessible to the selected clients or users. In other words, either the URL must be on an internal computer or some rule must explicitly allow access to the URL.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.ScheduleUsed Property

Gets the FPCRef object that is used to define the actual times when the rule applies.

VBScript Syntax[VBScript]

[ oFPCRef = ] FPCSiteAndContentRule.ScheduleUsed

C++ Syntax[C++]

HRESULT get_ScheduleUsed(
  IFPCRef **poFPCRef
);

Parameters

oFPCRef
Reference to an FPCRef object.

The property is read-only. It can be set through the SetSchedule method.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.SetAppliesAlways Method

Sets the site and content rule, which is represented by the FPCSiteAndContentRule object, to apply at all times and on all days. The ScheduleUsed property returns the schedule that usually defines the actual times when this rule applies. This schedule becomes meaningless when the SetAppliesAlways method is used.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.SetAppliesAlways()

C++ Syntax[C++]

HRESULT SetAppliesAlways();

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.SetDestination Method

Sets the destinations to which the rule applies.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.SetDestination( DestType, sDestSet, ItemScope )

C++ Syntax[C++]

HRESULT SetDestination (
  FpcDestinationSelection DestType,
  BSTR sDestSet,
  FpcItemScope ItemScope
);

Parameters

DestType
Required. Defines the type of destinations. It can have a value of the FpcDestinationSelection enumerated type.
sDestSet
Optional. String that specifies the destination set to use. Needed when DestType is set to fpcDestinationSet.
ItemScope
Optional. Item scope. This can have a value from the FpcItemScope enumerated type. When DestType is set to fpcDestinationSet, ItemScope defines the destination set as either an array policy or enterprise policy destination set. Has a default value of fpcArrayScope.This parameter is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

Remarks

When ISA Server processes a request for which path processing is not supported (for example, any non-HTTP request), ISA Server ignores all destinations for which a path is specified. This does not imply that ISA Server ignores the rule that references the destination. For example, assume that you have a rule that denies access to two destinations: //example.microsoft.com/example and widgets.microsoft.com. A request to access Network News Transfer Protocol (NNTP) content from example.microsoft.com will not be denied. A request to access NNTP content from widgets.microsoft.com will be denied.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.SetSchedule Method

Sets the schedule to which the rule applies.

VBScript Syntax[VBScript]

FPCSiteAndContentRule.SetSchedule( sScheduleName, ItemScope )

C++ Syntax[C++]

HRESULT SetSchedule(
  BSTR sScheduleName,
  FpcItemScope ItemScope
);

Parameters

sScheduleName
String specifying the name of the schedule to which the rule applies.
ItemScope
The item scope. Defines whether the schedule being set is from the local collection of schedules (array scope) or from the enterprise collection of schedules. It can have a value from the FpcItemScope enumerated type. Has a default value of fpcArrayScope.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRule.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCSiteAndContentRule object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCSiteAndContentRule.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSiteAndContentRule


FPCSiteAndContentRules Collection

The FPCSiteAndContentRules collection provides access to a group of FPCSiteAndContentRule objects. An individual FPCSiteAndContentRule object represents a site and content rule. A site and content rule defines actions that will be taken when specific users attempt to access specific sites or content by using the ISA server. ISA site and content rules allow you to define exactly which sites and content can be accessed by clients behind the ISA server. Site and content rules also determine when the rule is in effect by applying the rule during a specific schedule. The rules appear in this collection in order of their execution.

Site and content rules can be created at both the array level and at the enterprise level. When an array policy is allowed, then its site and content rules can only further restrict enterprise-level site and content rules. For more information about enterprise nad array policy, see Enterprise and Array Policy.

The FPCSiteAndContentRules collection is a property of the FPCArrayPolicy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCSiteAndContentRules interface.

Methods

The following table lists the methods of the FPCSiteAndContentRules collection.

Method | Description
Add | Creates a new FPCSiteAndContentRule object in the collection and returns a reference to it.
Item | Retrieves the given FPCSiteAndContentRule object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a site and content rule from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCSiteAndContentRules collection.

Property | Description
Count | Gets the number of FPCSiteAndContentRule objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data in the FPCSiteAndContentRules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSiteAndContentRules.Add Method

Creates a new FPCSiteAndContentRule object in the collection and returns a reference to it. The name must be unique; if this method is called with an existing name, Add will fail.

If the enterprise policy settings are configured to apply an enterprise policy, then site and content rule creation are restricted on the array level. If the enterprise policy does not allow array policy, then you cannot use this method to add a site and content rule on the array level. If the enterprise policy allows array policy, then the array's site and content rules can only further restrict enterprise-level site and content rules.

VBScript Syntax[VBScript]

[ oFPCSiteAndContentRule = ] FPCSiteAndContentRules.Add( sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  IFPCSiteAndContentRule **ppoFPCSiteAndContentRule
);

Parameters

sName
Required. String that specifies the name of the new rule.

Return Value

oFPCSiteAndContentRule
Reference to an FPCSiteAndContentRule object.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Count Property

Gets the number of FPCSiteAndContentRule objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCSiteAndContentRules.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of rule objects.

The property is read-only.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Item Method

Retrieves a given FPCSiteAndContentRule object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCSiteAndContentRules.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCSiteAndContentRule **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCSiteAndContentRule, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCSiteAndContentRules.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Remove Method

Removes an FPCSiteAndContentRule object from the collection.

VBScript Syntax[VBScript]

FPCSiteAndContentRules.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the object to remove.

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCSiteAndContentRules.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCSiteAndContentRules


FPCSiteAndContentRules.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCSiteAndContentRules collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCSiteAndContentRules.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCSiteAndContentRules


FPCSnapinNode Object

The FPCSnapinNode object is used to extend ISA Management.For more information, see Extending ISA Management.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCSnapinNode interface. It can be retrieved by querying the IDataObject interface of the ISA node that is to be extended:

DataObject->QueryInterface(IID_IFPCSnapinNode)

Methods

The following table lists the methods of the FPCSnapinNode object.

Method | Description
Refresh | Refreshes the ISA Management node represented by IFPCSnapinNode after the node has been changed.

Properties

The following table lists the properties of the FPCSnapinNode object.

Property | Description
ComRoot | Gets the FPC root object.
CurrentObject | Gets the object that you are extending.
ParentArray | Gets the array under which you create an extension.
ParentPolicy | Gets the FPCEnterprisePolicy under which you create an extension.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSnapinNode.ComRoot Property

Gets the FPC root object.

VBScript Syntax[VBScript]

[ Root = ] FPCSnapinNode.ComRoot

C++ Syntax[C++]

HRESULT get_ComRoot(
  IDispatch **pRoot
);

Parameters

Root
The FPC root object.

The property is read-only.

Applies To

FPCSnapinNode


FPCSnapinNode.CurrentObject Property

Gets the object that you are extending. Through this property you can access FPCVendorParametersSets.

VBScript Syntax[VBScript]

[ Object = ] FPCSnapinNode.CurrentObject( Object )

C++ Syntax[C++]

HRESULT get_CurrentObject(
  Dispatch **pObject
);

Parameters

Object
The current object.

The property is read-only.

Applies To

FPCSnapinNode


FPCSnapinNode.ParentArray Property

Gets the array under which you are creating an extension.The ParentArray property is an FPCArray object as exposed through the ISA administration COM object model.

VBScript Syntax[VBScript]

[ Array = ] FPCSnapinNode.ParentArray( Array )

C++ Syntax[C++]

HRESULT get_ParentArray(
  IDispatch **pArray
);

Parameters

Array
The parent array.

The property is read-only.

Applies To

FPCSnapinNode


FPCSnapinNode.ParentPolicy Property

Gets the FPCEnterprisePolicy under which you create an extension. The ParentPolicy property is an FPCEnterprisePolicy object as exposed through the ISA administration COM object model.

VBScript Syntax[VBScript]

[ Policy = ] FPCSnapinNode.ParentPolicy( Policy )

C++ Syntax[C++]

HRESULT get_ParentPolicy(
  IDispatch **pPolicy
);

Parameters

Policy
The enterprise policy.

The property is read-only.

Applies To

FPCSnapinNode


FPCSnapinNode.Refresh Method

Refreshes the ISA Management node represented by IFPCSnapinNode after the node has been changed.

VBScript Syntax[VBScript]

FPCSnapinNode.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

C++ Usage example[C++]

CComQIPtr<IFPCSnapinNode> spIFPCSnapinNode = m_pDataObject;
    if (spIFPCSnapinNode != NULL)
    {
        spIFPCSnapinNode->Refresh();
    }

Applies To

FPCSnapinNode


FPCSSLCertificate Object

The FPCSSLCertificate object represents an SSL server certificate stored on an ISA server computer. The FPCSSLCertificate provides read-only access to certificate information.

Note When an SSL certificate has been updated, the Web proxy (w3proxy) service must be restarted. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

This object is a member of the FPCSSLCertificates collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCSSLCertificate interface.

Properties

The following table lists the properties of the FPCSSLCertificate object.

Property | Description
ExpirationDate | Gets the certificate's expiration date.
FriendlyName | Gets the certificate's friendly name.
Hash | Gets the certificate's hash value.
IssuedBy | Gets the name of the entity that issued the certificate.
IssuedTo | Gets the entity to whom the certificate was issued.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSSLCertificate.ExpirationDate Property

Gets the expiration date of the certificate.

VBScript Syntax[VBScript]

[ Date = ] FPCSSLCertificate.ExpirationDate

C++ Syntax[C++]

HRESULT get_ExpirationDate(
  DATE *pDate
);

Parameters

Date
The expiration date.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.FriendlyName Property

Gets the friendly name of the certificate.

VBScript Syntax[VBScript]

[ sFriendlyName = ] FPCSSLCertificate.FriendlyName

C++ Syntax[C++]

HRESULT get_FriendlyName(
  BSTR *psFriendlyName
);

Parameters

sFriendlyName
A string that specifies the friendly name of the certificate.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.Hash Property

Gets the hash value of the certificate.

VBScript Syntax[VBScript]

[ vHash = ] FPCSSLCertificate.Hash

C++ Syntax[C++]

HRESULT get_Hash(
  VARIANT *pvHash
);

Parameters

vHash
The hash value.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.IssuedBy Property

Gets the name of the entity that issued the certificate.

VBScript Syntax[VBScript]

[ sIssuedBy = ] FPCSSLCertificate.IssuedBy

C++ Syntax[C++]

HRESULT get_IssuedBy(
  BSTR *psIssuedBy
);

Parameters

sIssuedBy
A string that specifies the entity that issued the certificate.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificate.IssuedTo Property

Gets the name of the entity to whom the certificate was issued.

VBScript Syntax[VBScript]

[ sIssuedTo = ] FPCSSLCertificate.IssuedTo

C++ Syntax[C++]

HRESULT get_IssuedTo(
  BSTR *psIssuedTo
);

Parameters

sIssuedTo
A string that specifies the entity to which the certificate was issued.

The property is read-only.

Applies To

FPCSSLCertificate


FPCSSLCertificates Collection

Represents a collection of FPCSSLCertificate objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCSSLCertificates interface.

Note If the contents of this collection change, the Web proxy (W3proxy) service must be restarted. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Methods

The following table lists the methods of the FPCSSLCertificate object.

Method | Description
Item | Retrieves the given FPCSSLCertificate object for the collection.
Refresh | Refreshes the FPCSSLCertificates collection to include certificates that may have been added to the server.

Properties

The following table lists the properties of the FPCSSLCertificate object.

Property | Description
Count | Gets the number of FPCSSLCertificate objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCSSLCertificates.Count Property

Gets the number of FPCSSLCertificate objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCSSLCertificates.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCSSLCertificate objects.

The property is read-only.

Applies To

FPCSSLCertificates


FPCSSLCertificates.Item Method

Retrieves the given FPCSSLCertificate object from the collection.

[ oFCPSSLCertificate = ] FPCSSLCertificates.Item( lIndex )

C++ Syntax[C++]

HRESULT Item(
  long lIndex,
  IFPCSSLCertificate **ppoFCPSSLCertificate
);

Parameters

lIndex
Required. One-based index of the object to retrieve.

Return Values

oFPCSSLCertificate
If successful, returns a reference to an object of type FPCSSLCertificate, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCSSLCertificates


FPCSSLCertificates.Refresh Method

Refreshes the FPCSSLCertificates collection to include certificates that may have been added to the server.

Note Certificates are not added by using the FPC objects.

VBScript Syntax[VBScript]

FPCSSLCertificates.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCSSLCertificates


FPCTunnelPortRange Object

The FPCTunnelPortRange object provides access to the tunnel port range.

A tunnel port allows ISA to work as a data pump for communication to particular ports on an external server. Because this effectively bypasses ISA protocol rules, the external port ranges for which this is possible are set by default to 443–443; that is, the single port 443 (SSL), and to 563–563, the single port 563 (NNTP). You can use the FPCTunnelPortRange object to change the port range in which a tunnel port can be created.

The following VBScript is an example of how to add ports to the tunnel port range.

set isa=CreateObject("FPC.Root")
set tprange=isa.Arrays.GetContainingArray.ArrayPolicy.WebProxy.TunnelPortRanges
set tmp=tprange.AddRange("SSL 3520", 3520, 3520)
set tmp=tprange.AddRange("SSL 3529", 3529, 3529)
tprange.Save

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCTunnelPortRange interface.

Methods

The following table lists the methods of the FPCTunnelPortRange object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCTunnelPortRange object.

Property | Description
Name | Gets the name of the port range.
TunnelHighPort | Sets the high end of the port range.
TunnelLowPort | Set the low end of the port range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCTunnelPortRange.Name Property

Gets or sets the tunnel port range name.

VBScript Syntax[VBScript]

FPCTunnelPortRange.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the tunnel port range name.

The property is read-write.

Applies To

FPCTunnelPortRange


FPCTunnelPortRange.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCTunnelPortRange.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCTunnelPortRange


FPCTunnelPortRange.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCTunnelPortRange.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCTunnelPortRange


FPCTunnelPortRange.TunnelHighPort Property

Gets or sets the high end of the port range.

VBScript Syntax[VBScript]

FPCTunnelPortRange.TunnelHighPort [ = lHighPort ]

C++ Syntax[C++]

HRESULT get_TunnelHighPort(
  long *plHighPort
);

HRESULT put_TunnelHighPort(
  long lHighPort
);

Parameters

lHighPort
Long value that specifies the high end of the port range.

The property is read-write.

Applies To

FPCTunnelPortRange


FPCTunnelPortRange.TunnelLowPort Property

Gets or sets the low end of the port range.

VBScript Syntax[VBScript]

FPCTunnelPortRange.TunnelLowPort [ = lLowPort ]

C++ Syntax[C++]

HRESULT get_TunnelLowPort(
  long *plLowPort
);

HRESULT put_TunnelLowPort(
  long lLowPort
);

Parameters

lLowPort
Long value that specifies the low end of the port range.

The property is read-write.

Applies To

FPCTunnelPortRange


FPCTunnelPortRanges Collection

The FPCTunnelPortRanges collection provides access to a group of FPCTunnelPortRange objects.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCTunnelPortRanges interface.

Methods

The following table lists the methods of the FPCTunnelPortRanges collection.

Method | Description
AddRange | Creates a new FPCTunnelPortRange object in the collection and returns a reference to it.
Item | Retrieves the given FPCTunnelPortRange object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCTunnelPortRange object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCTunnelPortRanges collection.

Property | Description
Count | Gets the number of FPCTunnelPortRange objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCTunnelPortRanges.AddRange Method

Creates a new FPCTunnelPortRange object in the collection and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCTunnelPortRange = ] FPCTunnelPortRanges.AddRange( sName, lLowPort, lHighPort )

C++ Syntax[C++]

HRESULT AddRange (
  BSTR sName,
  long lLowPort,
  long lHighPort,
  IFPCTunnelPortRange **ppoFPCTunnelPortRange
);

Parameters

sName
Required. String that specifies the name of the new FPCTunnelPortRange entry.
lLowPort
Required. Long value that specifies the low end of the port range.
lHighPort
Required. Long value that specifies the high end of the port range.

Return Values

oFPCTunnelPortRange
Reference to an FPCTunnelPortRange object.

Applies To

FPCTunnelPortRanges


FPCTunnelPortRanges.Count Property

Gets the number of FPCTunnelPortRange objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCTunnelPortRanges.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCTunnelPortRange objects.

The property is read-only.

Applies To

FPCTunnelPortRanges


FPCTunnelPortRanges.Item Method

Retrieves the given FPCTunnelPortRange object from the collection.

VBScript Syntax[VBScript]

[ oFPCTunnelPortRange = ] FPCTunnelPortRanges.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCTunnelPortRange **ppoFPCTunnelPortRange
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

oFPCTunnelPortRange
If successful, returns a reference to an object of type FPCTunnelPortRange, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCTunnelPortRanges


FPCTunnelPortRanges.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCTunnelPortRanges.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCTunnelPortRanges


FPCTunnelPortRanges.Remove Method

Removes an FPCTunnelPortRange object from the collection.

VBScript Syntax[VBScript]

FPCTunnelPortRanges.Remove( vItem )

C++ Syntax[C++]

HRESULT Remove (
  VARIANT vItem
);

Parameters

vItem
Required. One-based index of the object to remove.

Applies To

FPCTunnelPortRanges


FPCTunnelPortRanges.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCTunnelPortRanges.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCTunnelPortRanges


FPCVendorParametersSet Object

The FPCVendorParametersSet object is used to set and return any vendor-specific data. FPCVendorParametersSet objects are used to integrate third-party extensions into ISA. Most ISA objects that are used programmatically have a VendorParametersSets property and can therefore be extended.

This object is used to store data that is defined as {name, value} pairs by using the Value property. The following example stores a property named x having a value of 1:

FPCVendorParametersSet.Value("x") = 1

The phrase Value("x") will return the value.

Updates to this object are transactional. The data is stored as a single binary large object (BLOB). Note that on registry-based ISA server computers, the size of the object is limited to 1 megabyte.

This object is a member of the FPCVendorParametersSets collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCVendorParametersSet interface. An example of C++ usage of IFPCVendorParametersSet is provided as part of the topic How to Create an Application Filter, in the topic Reading Configuration from Vendor Parameter Sets.

Methods

The following table lists the methods of the FPCVendorParametersSet object.

Method | Description
CancelWaitForChanges | For use in C and C++ programming only; cancels the registration established by the WaitForChanges method.
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
RemoveValue | The RemoveValue method of the FPCVendorParametersSet object removes the given value from the set.
Save | Saves the object's configuration to persistent storage.
WaitForChanges | For use in C and C++ programming only; registers to wait for an event indicating that the FPCVendorParametersSet context has changed.

Properties

The following table lists the properties of the FPCVendorParametersSet object.

Property | Description
AllNames | Gets all the names of the parameters set.
Name | Gets or sets the name of the parameters set.
Value | Gets or sets the value associated with the given name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCVendorParametersSet.AllNames Property

Gets all the names of the parameters set.

VBScript Syntax[VBScript]

[ vItem = ]FPCVendorParametersSet.AllNames

C++ Syntax[C++]

HRESULT get_AllNames(
  VARIANT *pvItem
);

Parameters

vItem
Pointer to an array of strings.

The property is read-only.

Remarks

The AllNames property returns a list of all the names of user-defined properties stored through the Value property.

For example, the following uses the Value property to store two user-defined values, "1" and "2":

obj.Value("x") = 1
obj.Value("y") = 2

If the AllNames property is used now, it returns an array of strings containing the strings "x" and "y".

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.CancelWaitForChanges Method

Cancels the registration established by the WaitForChanges method.

Note This method can only be used in C and C++ programming languages. It cannot be used with DCOM.

C++ Syntax[C++]

HRESULT CancelWaitForChanges();


FPCVendorParametersSet.Name Property

Gets or sets the name of the parameters set.

VBScript Syntax[VBScript]

FPCVendorParametersSet.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the parameters set name.

The property is read-write.

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCVendorParametersSet.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.RemoveValue Method

Removes the given value from the set.

VBScript Syntax[VBScript]

FPCVendorParametersSet.RemoveValue( sValue )

C++ Syntax[C++]

HRESULT RemoveValue(
  BSTR sValue
);

Parameters

sValue
String that specifies the value to remove.

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCVendorParametersSet.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.Value Property

Gets or sets the value associated with the given name.

VBScript Syntax[VBScript]

FPCVendorParametersSet.Value (sName)[ = vValue ]

C++ Syntax[C++]

HRESULT get_Value(
  BSTR sName,
  VARIANT *pvValue
);

HRESULT put_Value(
  BSTR sName,
  VARIANT vValue
);

Parameters

sName
Specifies the parameter name for which to retrieve the value.
vValue
The value associated with the name. The value can be of almost any type and is not necessarily a string.

The property is read-write.

Remarks

The FPCVendorParametersSet object is used to store data that is defined as {name, value} pairs by using the Value property. The following example stores a property named x having a value of 1:

FPCVendorParametersSet.Value("x") = 1

The phrase Value("x") will return the value.

The Value property is also the default property. The following examples are equivalent:

obj.Value("x)
obj("x")

Applies To

FPCVendorParametersSet


FPCVendorParametersSet.WaitForChanges Method

Registers to wait for an event indicating that the contents of the FPCVendorParametersSet object have changed.

Note This method can only be used in C and C++ programming languages. It cannot be used with DCOM.

C++ Syntax[C++]

HRESULT WaitForChanges(
  DWORD hEvent
);

Parameters

hEvent
An event that will be signaled whenever the storage content of the FPCVendorParametersSet object has changed.

Remarks

This method allows application filters to handle dynamic configuration changes smoothly. Note that when you develop an application filter that uses the WaitForChanges method to handle dynamic changes, the FPCVendorParametersSet object should be preserved as long as is necessary to receive notifications. This can be done by making the FPCVendorParametersSet object a member of the filter (IFWXFilter) object.

It is possible to use Visual Basic to get notification of storage changes in the FPCVendorParametersSet object without using the WaitForChanges method, as shown in the following Visual Basic example. This approach will not work in scripting languages.

private sub objectname_OnChange
end sub
'In this example, code executes when the
'FPCVendorParametersSet object defined as pd changes
Dim FPC As New FPC
Dim WithEvents pd As FPCVendorParametersSet
Private Sub Start_Click()
  Set pd = FPC.Arrays(1).VendorParametersSets(1)

End Sub

Private Sub pd_OnChange()
  pd.Refresh
  MsgBox "pd_OnChange - user is:" & pd("UserName")
End Sub

Applies To

FPCVendorParametersSet


FPCVendorParametersSets Collection

The FPCVendorParametersSets collection is used to access the collection of FPCVendorParametersSet objects. Most ISA objects have a VendorParametersSets property that is a reference to this FPCVendorParametersSets collection. A third party can use this collection to associate private sets of configuration information with the object being extended. All objects that have a VendorParametersSets property are extensible.

Each set is identified by a globally unique identifier (GUID) that is provided to the Add method when a new set is created.

By using the FPCVendorParametersSets collection also permits a third party to take advantage of the backup-and-restore capabilities of ISA. Any data stored in this collection is backed up with the rest of the objects whenever a backup is done. The third-party data is also saved to the Active Directory, when available, by the Save method of this collection, or whenever the Save method of the object being extended is called. You don't need to write code to read and write directly from the Registry or the Active Directory when using this collection because reading from and writing to storage are taken care of by the Save and Refresh methods.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCVendorParametersSets interface.

Methods

The following table lists the methods of the FPCVendorParametersSets collection.

Method | Description
Add | Creates a new FPCVendorParametersSet object, inserts it into the collection, and returns a reference to it.
Item | Returns the given FPCVendorParametersSet object from the collection.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a parameters set from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCVendorParametersSets collection.

Property | Description
Count | Gets the number of FPCVendorParametersSet objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCVendorParametersSets.Add Method

Creates a new FPCVendorParametersSet object, inserts it into the collection, and returns a reference to it.

VBScript Syntax[VBScript]

[ oFPCVendorParametersSet = ] FPCVendorParametersSets.Add( sGuid, bEncrypted )

C++ Syntax[C++]

HRESULT Add(
  BSTR sGuid,
  VARIANT_BOOL bEncrypted,
  IFPCVendorParametersSet **ppoFPCVendorParametersSet
);

Parameters

sGuid
Required. String that specifies the GUID of the new object.
bEncrypted
Optional. A Boolean expression. If TRUE, the data will be saved in an encrypted form, and only calls under the local system account will be able to read the data. If FALSE, the data will not be saved in encrypted form.

Note A user that has permission to access storage, but not to read the encrypted data, will retrieve an empty FPCVendorParametersSet object. Then, when that user makes changes to the object and saves it to storage, the original FPCVendorParametersSet will be overwritten, and only the data added by that user will be saved.

Return Values

oFPCVendorParametersSet
Returns a reference to the FPCVendorParametersSet object.

Remarks

The GUID must be in the following format:

"{482acfde-0a4a-479b-b856-3206a1fe2a6c}"

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Count Property

Gets the number of parameters set objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCVendorParametersSets.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCVendorParametersSet objects.

The property is read-only.

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Item Method

Returns the given FPCVendorParametersSet object from the collection.

VBScript Syntax[VBScript]

[ oFPCVendorParametersSet = ] FPCVendorParametersSets.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCVendorParametersSet **poFPCVendorParametersSet
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Values

oFPCVendorParametersSet
If successful, returns a reference to an object of type FPCVendorParametersSet, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCVendorParametersSets.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Remove Method

Removes a parameters set from the collection.

VBScript Syntax[VBScript]

FPCVendorParametersSets.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. Name or one-based index of the FPCVendorParametersSet object to remove.

Applies To

FPCVendorParametersSets


FPCVendorParametersSets.Save Method

Saves the configuration of all FPCVendorParametersSet objects to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCVendorParametersSets.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCVendorParametersSets


FPCWebBrowserClientConfig Object

The FPCWebBrowserClientConfig object represents the browser configuration and is a property of the FPCClientConfig object. You can set a client's Web browser settings so that a client will work with the ISA Web proxy service. That configuration is represented by FPCWebBrowserClientConfig. This object generates a configuration file for clients that use the ISA server as a Web proxy service. This configuration file will be used by the ISA client setup to configure the browsers on users' computers.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCWebBrowserClientConfig interface.

Methods

The following table lists the methods of the FPCWebBrowserClientConfig object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetBrowserConfigScript | Sets whether the default or custom script is used.

Properties

The following table lists the properties of the FPCWebBrowserClientConfig object.

Property | Description
AutoScript | Gets a reference to the FPCClientAutoScript object.
BrowserConfigAutoDetect | Gets or sets whether automatic configuration settings are automatically detected.
BrowserConfigEnabled | Gets or sets whether the ISA Server client installation will affect the client's browser settings.
BrowserConfigScriptAddress | Gets the address (URL) or file name of the file that will be used to configure the browser.
BrowserConfigScriptEnabled | Gets or sets whether the browser will use the information in the configuration file.
BrowserConfigScriptFlag | Gets whether the browser configuration uses a default script or a custom script.
ServerOrArrayName | Gets or sets the name of the proxy server. This name is translated by the Domain Name System (DNS) and can point to multiple proxy servers.
VendorParametersSets | Getsa reference to an object for storing and loading of custom data.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebBrowserClientConfig.AutoScript Property

Gets a reference to an FPCClientAutoScript object.

VBScript Syntax[VBScript]

[ oFPCClientAutoScript = ] FPCWebBrowserClientConfig.AutoScript

C++ Syntax[C++]

HRESULT get_AutoScript (
  IFPCClientAutoScript **poFPCClientAutoScript
);

Return Values

oFPCClientAutoScript
Returns a reference to an FPCClientAutoScript object.

The property is read-only.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigAutoDetect Property

Gets or sets whether automatic configuration settings are automatically detected.

The automatic discovery feature of ISA Server allows you to configure Web proxy clients so that they automatically discover the appropriate ISA Server computer. In this way, roaming clients can connect to the ISA Server computer, as appropriate and when necessary.

VBScript Syntax[VBScript]

FPCWebBrowserClientConfig.BrowserConfigAutoDetect[ = bAutoDetect ]

C++ Syntax[C++]

HRESULT get_BrowserConfigAutoDetect(
  VARIANT_BOOL *pbAutoDetect
);

HRESULT put_BrowserConfigAutoDetect(
  VARIANT_BOOL bAutoDetect
);

Return Values

bAutoDetect
Boolean value that specifies whether the settings will be automatically detected.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigEnabled Property

Gets or sets whether the ISA Server Firewall client installation will affect the client's Web browser settings.

VBScript Syntax[VBScript]

FPCWebBrowserClientConfig.BrowserConfigEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_BrowserConfigEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT BrowserConfigEnabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that determines if affect on browser is enabled.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigScriptAddress Property

Gets the address (URL) or file name of the file that will be used to configure the browser.

VBScript Syntax[VBScript]

[ sAddress = ] FPCWebBrowserClientConfig.BrowserConfigScriptAddress

C++ Syntax[C++]

HRESULT get_BrowserConfigScriptAddress(
  BSTR *psAddress
);

Return Values

sAddress
A string that specifies the address or name of the file.

This property is read-only.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigScriptEnabled Property

Gets or sets whether the browser will use the information in the configuration file.

VBScript Syntax[VBScript]

FPCWebBrowserClientConfig.BrowserConfigScriptEnabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_BrowserConfigScriptEnabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_BrowserConfigScriptEnabled(
  VARIANT_BOOL bEnabled
);

Return Values

bEnabled
Boolean value that specifies whether the browser will use the information in the configuration file.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.BrowserConfigScriptFlag Property

Gets whether the browser configuration uses a default script or a custom script.

VBScript Syntax[VBScript]

[ ConfigScript = ] FPCWebBrowserClientConfig.BrowserConfigScriptFlag

C++ Syntax[C++]

HRESULT get_BrowserConfigScriptFlag(
  FpcBrowserConfigScriptFlag *pConfigScript
);

Return Values

ConfigScript
A flag that indicates whether the default or custom script is used. Can have a value of either fpcBrowserDefaultScript, or fpcBrowserCustomScript from the FpcBrowserConfigScriptFlag enumerated type.

The property is read-only.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCWebBrowserClientConfig.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCWebBrowserClientConfig.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.ServerOrArrayName Property

Gets or sets the name of the ISA Server or array. This name is translated by the Domain Name System (DNS) and can point to multiple proxy servers.

VBScript Syntax[VBScript]

FPCWebBrowserClientConfig.ServerOrArrayName [ = sName ]

C++ Syntax[C++]

HRESULT get_ServerOrArrayName(
  BSTR *psName
);

HRESULT put_ServerOrArrayName(
  BSTR sName
);

Parameters

sName
String that specifies the name of the ISA Server or array.

The property is read-write.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.SetBrowserConfigScript Method

Sets whether the default or custom script is used.

VBScript Syntax[VBScript]

FPCWebBrowserClientConfig.SetBrowserConfigScript( ConfigScript, sScript )

C++ Syntax[C++]

HRESULT SetBrowserConfigScript(
  FpcBrowserConfigScriptFlag ConfigScript,
  BSTR sScript
);

Parameters

ConfigScript
Can have a value from the FpcBrowserConfigScriptFlag enumerated type.
sScript
String that identifies a configuration script.

Applies To

FPCWebBrowserClientConfig


FPCWebBrowserClientConfig.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data.The VendorParametersSets property allows third-party extensions to be integrated into ISA.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCWebBrowserClientConfig.VendorparametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebBrowserClientConfig


FPCWebFilter Object

The FPCWebFilter object represents a single Web (ISAPI) filter that is registered to extend the ISA Web proxy service. Web filters are dynamic-link libraries (DLLs) that are loaded when the ISA Web proxy service is started and stay in memory until the service shuts down. Once loaded, Web filters can be configured to receive a number of special filter-event notifications. These filter-event notifications occur with each HTTP request that the ISA Web proxy service receives and with each response returned through the ISA Web proxy by an external Web server.

This object is a member of the FPCWebFilters collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCWebFilter interface.

Note When you've made and saved Web filter configuration changes the Web proxy (W3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Methods

The following table lists the methods of the FPCWebFilter object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCWebFilter object.

Property | Description
Description | Gets or sets the vendor-supplied description of the filter.
Enabled | Gets or sets whether the filter is enabled.
FilterDirection | Gets the direction of the filter.
Guid | Gets the globally unique identifier (GUID) that identifies the filter. The vendor of the filter provides the GUID.
Name | Gets or sets the vendor-supplied name of the filter.
Order | Gets the filter's order.
Priority | Gets or sets the filter's priority.
RelativePath | Gets or sets the filter dynamic-link library DLL path relative to ISA-install-dir\isapi.
Vendor | Gets or sets the name of the vendor of the filter.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCWebFilter object's storage.
Version | Gets or sets the vendor-supplied version of the filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebFilter.Description Property

Gets or sets the vendor-supplied description of the filter.

VBScript Syntax[VBScript]

FPCWebFilter.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the vendor-supplied description.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.Enabled Property

Gets or sets whether the filter is enabled.

VBScript Syntax[VBScript]

FPCWebFilter.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the filter is enabled.

The property is read-write.

Note When you enable or disable a Web filter, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Applies To

FPCWebFilter


FPCWebFilter.FilterDirection Property

Gets whether the filter operates in reverse proxy, forward proxy, or both configurations. You set this property when you add a filter by using the FPCWebFilters.Add method.

VBScript Syntax[VBScript]

[ FilterDirection = ] FPCWebFilter.FilterDirection

C++ Syntax[C++]

HRESULT get_FilterDirection(
  FpcFilterDirection *pFilterDirection
);

Return Value

FilterDirection
Returns a value from the FpcFilterDirection enumerated type.

The property is read only.

Applies To

FPCWebFilter


FPCWebFilter.Guid Property

Gets the globally unique identifier (GUID) that identifies the filter. The vendor of the filter provides the GUID.

VBScript Syntax[VBScript]

[ sGuid = ] FPCWebFilter.Guid

C++ Syntax[C++]

HRESULT get_Guid(
  BSTR *psGuid
);

Parameters

sGuid
String that specifies the GUID for the filter.

The property is read-only.

Applies To

FPCWebFilter


FPCWebFilter.Name Property

Gets or sets the vendor-supplied name of the filter.

VBScript Syntax[VBScript]

FPCWebFilter.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the vendor-supplied name.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.Order Property

Gets the filter's order. This property is set by using the FPCWebFilters.MoveUp and FPCWebFilters.MoveDown methods. Filter order establishes the order in which filters of the same priority receive the data.

VBScript Syntax[VBScript]

[ lOrder = ] FPCWebFilter.Order

C++ Syntax[C++]

HRESULT Order(
  long *plOrder
);

Parameters

lOrder
Long value that specifies the order of the filter.

The property is read-only.

Applies To

FPCWebFilter


FPCWebFilter.Priority Property

Gets or sets the priority of the filter.

VBScript Syntax[VBScript]

FPCWebFilter.Priority [ = FpcFilterPriority ]

C++ Syntax[C++]

HRESULT get_Priority(
  FpcFilterPriority *pFpcFilterPriority
);

HRESULT put_Priority(
  FpcFilterPriority FpcFilterPriority
);

Parameters

FpcFilterPriority
Filter priority. Can have a value of fpcFilterPriority_Low, fpcFilterPriority_Medium, or fpcFilterPriority_High from the FpcFilterPriority enumerated type.

The property is read-write.


FPCWebFilter.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCWebFilter.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCWebFilter


FPCWebFilter.RelativePath Property

Gets or sets the filter DLL path relative to ISA-install-dir\isapi.

VBScript Syntax[VBScript]

FPCWebFilter.RelativePath [ = sPath ]

C++ Syntax[C++]

HRESULT get_RelativePath(
  BSTR *psPath
);

HRESULT put_RelativePath(
  BSTR sPath
);

Parameters

sPath
String that specifies the relative path.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCWebFilter.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCWebFilter


FPCWebFilter.Vendor Property

Gets or sets the name of the vendor of the filter.

VBScript Syntax[VBScript]

FPCWebFilter.Vendor [ = sVendor ]

C++ Syntax[C++]

HRESULT get_Vendor(
  BSTR *psVendor
);

HRESULT put_Vendor(
  BSTR sVendor
);

Parameters

sVendor
String that specifies the vendor's name.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilter.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCWebFilter object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCWebFilter.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebFilter


FPCWebFilter.Version Property

Gets or sets the vendor-supplied version of the filter.

VBScript Syntax[VBScript]

FPCWebFilter.Version [ = sVersion ]

C++ Syntax[C++]

HRESULT get_Version(
  BSTR *psVersion
);

HRESULT put_Version(
  BSTR sVersion
);

Parameters

sVersion
String that specifies the vendor-supplied version.

The property is read-write.

Applies To

FPCWebFilter


FPCWebFilters Collection

The FPCWebFilters collection provides access to a group of FPCWebFilter objects.

This object is a member of the FPCPolicyElements object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCWebFilters interface.

Note When you've made and saved Web filter configuration changes the Web proxy (W3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Methods

The following table lists the methods of the FPCWebFilters collection.

Method | Description
Add | Adds a new FPCWebFilter object to the collection.
Item | Retrieves the given FPCWebFilter object from the collection.
MoveDown | Moves the given filter one step down in the filter order.
MoveUp | Moves the given filter one step up in the filter order.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes a filter object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCWebFilters collection.

Property | Description
Count | Gets the number of Web filters in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebFilters.Add Method

Adds a new FPCWebFilter object.

VBScript Syntax[VBScript]

[ oFPCWebFilter = ] FPCWebFilter .Add( sGuid, sName, sRelativePath, FpcFilterPriority, Direction )

C++ Syntax[C++]

HRESULT Add(
  BSTR sGuid,
  BSTR sName,
  BSTR sRelativePath,
  FpcFilterPriority FpcFilterPriority,
  FpcFilterDirection Direction,
  IFPCWebFilter **ppoFPCWebFilter
);

Parameters

sGuid
Required. String that specifies the GUID of the new filter.
sName
Required. String that specifies the display name of the new filter.
sRelativePath
Required. String that specifies the path of the filter DLL relative to the ISA installation directory (such as \Program Files\Microsoft ISA Server\.
FpcFilterPriority
Filter priority. Can have a value from the FpcFilterPriority enumerated type.
Direction
Filter direction. Can have a value from the FpcFilterDirection enumerated type, including reverse, forward, or both directions.

Return Value

oFPCWebFilter
Returns a reference to the new FPCWebFilter object.

Note When you add a Web filter to the FPCWebFilters collection, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.Count Property

Gets the number of Web (ISAPI) filters in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCWebFilters.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of filter objects.

The property is read-only.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.Item Method

Retrieves the given FPCWebFilter object from the collection.

VBScript Syntax[VBScript]

[ oFPCWebFilter = ] FPCWebFilters.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCWebFilter **poFPCWebFilter
);

Parameters

vIndex
Required. GUID or one-based index of the object to retrieve.

Return Values

oFPCWebFilter
If successful, returns a reference to an object of type FPCWebFilter, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.MoveDown Method

Moves the given filter one step down in the filter order .

VBScript Syntax[VBScript]

FPCWebFilters.MoveDown( lIndex )

C++ Syntax[C++]

HRESULT MoveDown(
  long lIndex
);

Parameters

lIndex
Required. Index (current order) of the filter to move down in the filter order.

Note When you change the order of the Web filters, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Applies To

FPCWebFilters

See Also

MoveUp


FPCWebFilters.MoveUp Method

Moves the given filter one step up in the filter order.

VBScript Syntax[VBScript]

FPCWebFilters.MoveUp( lIndex )

C++ Syntax[C++]

HRESULT MoveUp(
  long lIndex
);

Parameters

lIndex
Required. Index (current order) of the filter to move up in the filter order.

Note When you change the order of the Web filters, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Applies To

FPCWebFilters

See Also

MoveDown


FPCWebFilters.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCWebFilters.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCWebFilters


FPCWebFilters.Remove Method

Removes a Web filter object from the collection.

VBScript Syntax[VBScript]

FPCWebFilters.Remove( vIndex )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vIndex
);

Parameters

vIndex
Required. GUID or one-based index of the object to remove.

Note When you remove a Web filter from the FPCWebFilters collection, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Applies To

FPCWebFilters

See Also

FPCWebFilter


FPCWebFilters.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCWebFilters.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCWebFilters


FPCWebFilters.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCWebFilters.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebFilters


FPCWebProxy Object

The FPCWebProxy object defines Web proxy authentication attributes. You can use this object to determine whether the Web proxy is set to always authenticate client requests to the server and to determine the authentication type.

The FPCWebProxy object is a property of the FPCArrayPolicy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCWebProxy interface.

Methods

The following table lists the methods of the FPCWebProxy object.

Method | Description
Refresh | Reads the object's configuration information from the Web proxy service using a remote procedure call (RPC), discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCWebProxy object.

Property | Description
AutoDiscoveryPort | Gets or sets the port to bind to if EnableAutoDiscovery is TRUE.
CARPNameSystem | Gets or sets whether CARP uses a DNS or WINS name system.
DeniedMethods | Gets the collection of HTTP-like protocols that have been denied by the ISA administrator.
EnableAutoDiscovery | Gets or sets whether the Web proxy binds to a specified port on all internal interfaces and returns the routing script as a response to a wpad.dat request.
IncomingWebRequests | Returns a reference to the FPCWebRequestConfiguration object.
LoadSize | Gets or sets the performance tuning of servers in your array, based on the expected number of users.
OutgoingWebRequests | Returns a reference to the FPCWebRequestConfiguration object.
TunnelPortRanges | Retrieves a reference to an FPCTunnelPortRanges collection.
UpstreamResolveSystem | Gets or sets whether a downstream server will use DNS or WINS information provided by an upstream server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebProxy.AutoDiscoveryPort Property

Gets or sets the port to bind to if the EnableAutoDiscovery property is TRUE.

VBScript Syntax[VBScript]

FPCWebProxy.AutoDiscoveryPort [= lPort ]

C++ Syntax[C++]

HRESULT get_AutoDiscoveryPort(
  long *plPort
);

HRESULT put_AutoDiscoveryPort(
  long lPort
);

Parameters

lPort
Long value that specifies the port to bind to if EnableAutoDiscovery is TRUE.

The property is read-write.

Remarks

The automatic discovery feature of ISA Server allows you to configure clients so that they automatically discover the appropriate ISA Server computer. In this way, roaming clients can connect to the ISA Server computer, as appropriate and when necessary. By enabling automatic discovery, Web proxy and Firewall clients all automatically discover the appropriate ISA Server computer.

Applies To

FPCWebProxy


FPCWebProxy.CARPNameSystem Property

Gets or sets whether a Web proxy computer uses a Domain Name System (DNS) or Windows Internet Name Service (WINS) name system. This is important because some computers do not have WINS names and will not work in CARP if you don't enable DNS name use.

Note This property is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

VBScript Syntax[VBScript]

FPCWebProxy.CARPNameSystem [= FpcNameSystem ]

C++ Syntax[C++]

HRESULT get_CARPNameSystem(
  FpcNameSystem *pFpcNameSystem
);

HRESULT put_CARPNameSystem(
  FpcNameSystem FpcNameSystem
);

Parameters

FpcNameSystem
The name system. It can have a value of fpc_NameSystem_DNS or fpc_NameSystem_WINS from the FpcNameSystem enumerated type.

The property is read-write.

Applies To

FPCWebProxy


FPCWebProxy.DeniedMethods Property

Gets the FPCDeniedMethods collection of HTTP-like protocols that have been denied by the ISA administrator.

This method denial feature can be accessed only through the ISA COM objects, not through ISA Management.

VBScript Syntax[VBScript]

[ collFpcDeniedMethods = ] FPCWebProxy.DeniedMethods

C++ Syntax[C++]

HRESULT get_DeniedMethods(
  IFpcDeniedMethods **pcollFpcDeniedMethods
);

Parameters

collFpcDeniedMethods
Returns a reference to the FPCDeniedMethods collection

The property is read only.

Remarks

There are protocols other than HTTP that use HTTP-like methods. The FPCDeniedMethods collection of FPCDeniedMethod objects allows an administrator to block the use of specific protocols by denying connections for specific methods.

Note By default, all of the HTTP-like methods are permitted unless specifically denied by the administrator.

Applies To

FPCWebProxy


FPCWebProxy.EnableAutoDiscovery Property

Gets or sets whether the Web proxy binds to a specified port on all internal interfaces and returns the routing script as a response to a wpad.dat request.

VBScript Syntax[VBScript]

FPCWebProxy.EnableAutoDiscovery [= bEnabled ]

C++ Syntax[C++]

HRESULT get_EnableAutoDiscovery(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_EnableAutoDiscovery(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that has either of these settings:
Setting | Meaning
TRUE | The Web proxy binds to port 80 on all local interfaces.
FALSE | The Web proxy does not bind to port 80 on all local interfaces.

The property is read-write.

Remarks

The automatic discovery feature of ISA Server allows you to configure clients so that they automatically discover the appropriate ISA Server computer. In this way, roaming clients can connect to the ISA Server computer, as appropriate and when necessary. By enabling automatic discovery, Web proxy and Firewall clients all automatically discover the appropriate ISA Server computer.

Applies To

FPCWebProxy


FPCWebProxy.IncomingWebRequests Property

Gets a reference to a FPCWebRequestConfiguration object. The FPCWebRequestConfiguration object provides access to the properties of forward proxy and reverse proxy.

VBScript Syntax[VBScript]

[ oFPCWebRequestConfiguration = ] FPCWebProxy.IncomingWebRequests

C++ Syntax[C++]

HRESULT get_InComingWebRequests(
  IFPCWebRequestConfiguration **poFPCWebRequestConfiguration
);

Parameters

oFPCWebRequestConfiguration
Returns a reference to the FPCWebRequestConfiguration object.

The property is read-only.

Applies To

FPCWebProxy


FPCWebProxy.LoadSize Property

Gets or sets the performance tuning of servers in your array, based on the expected number of users.

Note This property is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

VBScript Syntax[VBScript]

FPCWebProxy.LoadSize [= FpcLoadSize ]

C++ Syntax[C++]

HRESULT get_LoadSize(
  FpcLoadSize *pFpcLoadSize
);

HRESULT put_LoadSize(
  FpcLoadSize FpcLoadSize
);

Parameters

FpcLoadSize
The load size, representing the expected number of users. Can have a value of fpcLoadSize_Small (less than 100 users per day), fpcLoadSize_Medium (less than 1000 users per day), or fpcLoadSize_Large (more than 1000 users per day) from the FpcLoadSize enumerated type.

The property is read-write.

Applies To

FPCWebProxy


FPCWebProxy.OutgoingWebRequests Property

Gets a reference to an FPCWebRequestConfiguration object. The FPCWebRequestConfiguration object provides access to the properties of forward proxy and reverse proxy.

VBScript Syntax[VBScript]

[ oFPCWebRequestConfiguration = ] FPCWebProxy.OutgoingWebRequests

C++ Syntax[C++]

HRESULT get_OutgoingWebRequests(
  IFPCWebRequestConfiguration **poFPCWebRequestConfiguration
);

Parameters

oFPCWebRequestConfiguration
Returns a reference to the FPCWebRequestConfiguration object.

The property is read-only.

Applies To

FPCWebProxy


FPCWebProxy.Refresh Method

Reads the object's configuration information from the Web proxy service by using a remote procedure call (RPC), discarding any changes to the configuration that were not saved.

VBScript Syntax[VBScript]

FPCWebProxy.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCWebProxy


FPCWebProxy.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCWebProxy.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCWebProxy


FPCWebProxy.TunnelPortRanges Property

Gets a reference to an FPCTunnelPortRanges collection.

VBScript Syntax[VBScript]

[ collFPCTunnelPortRanges = ] FPCWebProxy.TunnelPortRanges

C++ Syntax[C++]

HRESULT get_TunnelPortRanges(
  IFPCTunnelPortRanges **pcollFPCTunnelPortRanges
);

Parameters

collFPCTunnelPortRanges
Reference to an FPCTunnelPortRanges collection.

The property is read-only.

Applies To

FPCWebProxy


FPCWebProxy.UpstreamResolveSystem Property

Gets or sets which information the ISA server will use to resolve the name of an upstream server, either Domain Name System (DNS) and Windows Internet Name Service (WINS) name system information, both of which are returned by an upstream server.

VBScript Syntax[VBScript]

FPCWebProxy.UpstreamResolveSystem [= FpcNameSystem ]

C++ Syntax[C++]

HRESULT get_UpstreamResolveSystem(
  FpcNameSystem *pFpcNameSystem
);

HRESULT put_UpstreamResolveSystem(
  FpcNameSystem FpcNameSystem
);

Parameters

FpcNameSystem
The name system. It can have a value of fpc_NameSystem_DNS or fpc_NameSystem_WINS from the FpcNameSystem enumerated type.

The property is read-write.

Applies To

FPCWebProxy


FPCWebPublishingRule Object

The FPCWebPublishingRule object representsa Web publishing rule. Web publishing rules determine how ISA Server should intercept incoming requests for HTTP objects on an internal Web server and how ISA Server should respond on behalf of the Web server. Requests are forwarded downstream to an internal Web server, located behind the ISA Server computer. If possible, the request is serviced from the ISA Server cache.

A Web publishing rule defines the response to attempts by outside users to access an internal site. Possible responses include:

  • Denying the request.
  • Delegating the request to a different internal server.

Publishing rules cannot be created at the enterprise level. However, the enterprise administrator can specify, by using the FPCEnterprise.AllowPublishing property, whether an array is allowed to publish servers. If the array is allowed to publish, the array administrator can create Web publishing rules (FPCWebPublishingRule object) or server publishing rules (FPCServerPublishingRule object). If the enterprise policy does not allow publishing, then an attempt to add a Web or server publishing rule will return an error message.

This object is a member of the FPCWebPublishingRules collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCWebPublishingRule interface.

Methods

The following table lists the methods of the FPCWebPublishingRule object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.
SetDestination | Sets the destinations to which the rule applies.
SetWebSiteAndPorts | Sets the action to Redirect and sets the redirect Web site and ports.

Properties

The following table lists the properties of the FPCWebPublishingRule object.

Property | Description
Action | Gets the action that this rule performs.
AppliesToAccounts | Gets the collection of accounts to which the rule applies.
AppliesToDestination | Gets the type of destination to which the rule applies.
AppliesToMethod | Gets or sets the method used for deciding to which users the rule applies.
ClientAddressSetsExcluded | Gets the collection of client address sets to which the rule does not apply.
ClientAddressSetsUsed | Gets the collection of client address sets to which the rule applies.
Description | Gets or sets the description of the rule.
DestinationSetUsed | Gets an FPCRef object that contains the name of the FPCRefs collection used to define the destination to which the rule applies.
Enabled | Gets or sets whether the rule is enabled.
FTPRedirectPort | Gets the port to redirect a request if the Web proxy service redirects it as an FTP request.
HTTPRedirectPort | Gets the port to redirect a request if the Web proxy service redirects it as an HTTP request.
IsDefault | Gets whether the rule is a preinstalled rule that cannot be deleted.
Name | Gets or sets the name of the publishing rule.
NonSecureProtocolRedirection | Gets or sets the protocol used when delegating a request that came on a nonsecure channel.
Order | Gets the rule's order of execution in relation to the other rules.
SecureProtocolRedirection | Gets or sets the protocol used when delegating a request that came on a nonsecure channel.
SendOriginalHostHeader | Gets or sets whether ISA Server sends the original host header, or the header related to the site specified in the Web publishing rule.
SSLClientCertificate | Gets or sets how the Web proxy handles client certificates.
SSLRedirectPort | Gets the port to redirect requests if redirecting as an SSL request.
SSLRequireSecureChannel | Gets or sets whether a secure channel is required.
VendorParametersSets | Gets a reference to an object for storing and loading of custom data into the FPCWebPublishingRule object's storage.
WebSite | Gets the Web site to redirect requests to when the Action property is set to the value fpcRouteRedirect.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebPublishingRule.Action Property

Gets the action that this rule performs. Possible actions are:

  • Refusing requests.
  • Forwarding requests to the server or servers used for Internet publishing

VBScript Syntax[VBScript]

[ PublishRouteType = ]FPCWebPublishingRule.Action

C++ Syntax[C++]

HRESULT get_Action(
  FpcPublishRouteType *pPublishRouteType
);

Parameters

PublishRouteType
Action that this rule performs. It can have a value of the FpcPublishRoute enumerated type.

The property is read only. Set the action by using the Action parameter of the SetWebSiteAndPorts method.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.AppliesToAccounts Property

Gets the collection of accounts for which the rule applies.

VBScript Syntax[VBScript]

[ collFPCAccounts = ] FPCWebPublishingRule.AppliesToAccounts

C++ Syntax[C++]

HRESULT get_AppliesToAccounts(
  IFPCAccounts **pcollFPCAccounts
);

Parameters

collFPCAccounts
Reference to an FPCAccounts collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.AppliesToDestination Property

Gets the type of destination to which the rule applies.

VBScript Syntax[VBScript]

[ DestinationSelection = ] FPCWebPublishingRule.AppliesToDestination

C++ Syntax[C++]

HRESULT get_AppliesToDestination(
  FpcDestinationSelection *pDestinationSelection
);

Parameters

DestinationSelection
Type of destination to which the rule applies. It can have a value of the FpcDestinationSelection enumerated type.

The property is read-only. It can be set through the SetDestination method.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.AppliesToMethod Property

Gets or sets the method used for deciding to which users the rule applies.

VBScript Syntax[VBScript]

FPCWebPublishingRule.AppliesToMethod [ = AppliesToType ]

C++ Syntax[C++]

HRESULT get_AppliesToMethod(
  FpcAppliesToType *pAppliesToType
);

HRESULT put_AppliesToMethod(
  FpcAppliesToType AppliesToType
);

Parameters

AppliesToType
Applicability method. It can have a value of the FpcAppliesToType enumerated type.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.ClientAddressSetsExcluded Property

Gets the collection of client address sets to which the publishing rule does not apply. This property is useful only when the ClientSetsUsed property is not empty. It allows you to design a rule that applies to one set of clients but excludes another set of clients.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCWebPublishingRule.ClientAddressSetsExcluded

C++ Syntax[C++]

HRESULT get_ClientAddressSetsExcluded(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.ClientAddressSetsUsed Property

Gets the collection of client address sets to which the publishing rule applies.

VBScript Syntax[VBScript]

[ collFPCRefs = ] FPCWebPublishingRule.ClientAddressSetsUsed

C++ Syntax[C++]

HRESULT get_ClientAddressSetsUsed(
  IFPCRefs **pcollFPCRefs
);

Parameters

collFPCRefs
Reference to the FPCRefs collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Description Property

Gets or sets the description of the Web publishing rule.

VBScript Syntax[VBScript]

FPCWebPublishingRule.Description [ = sDescription ]

C++ Syntax[C++]

HRESULT get_Description(
  BSTR *psDescription
);

HRESULT put_Description(
  BSTR sDescription
);

Parameters

sDescription
String that specifies the description of the rule.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.DestinationSetUsed Property

Gets an FPCRef object used to define the destination to which the rule applies.

VBScript Syntax[VBScript]

[ collFPCRef = ] FPCWebPublishingRule.DestinationSetUsed

C++ Syntax[C++]

HRESULT get_DestinationSetUsed(
  IFPCRef **pcollFPCRef
);

Parameters

collFPCRef
The FPCRef object used to define the destination to which the rule applies.

The property is read-only. It can be set by using the SetDestination method.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Enabled Property

Gets or sets whether the rule is enabled.

VBScript Syntax[VBScript]

FPCWebPublishingRule.Enabled [ = bEnabled ]

C++ Syntax[C++]

HRESULT get_Enabled(
  VARIANT_BOOL *pbEnabled
);

HRESULT put_Enabled(
  VARIANT_BOOL bEnabled
);

Parameters

bEnabled
Boolean value that specifies whether the rule is enabled.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.FTPRedirectPort Property

Gets the port to redirect a request if the Web proxy service redirects it as an FTP request. To set the port, use the SetWebSiteAndPorts method.

Note Rule requirements, including redirection requirements, are addressed by the member of the array that actually handles the request, after intra-array resolution (using CARP) is completed.

VBScript Syntax[VBScript]

[ lFTPRedirectPort = ]FPCWebPublishingRule.FTPRedirectPort

C++ Syntax[C++]

HRESULT get_FTPRedirectPort(
  long *plFTPRedirectPort
);

Parameters

lFTPRedirectPort
Long value that specifies the port.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.HTTPRedirectPort Property

Gets the port to redirect requests if redirecting as an HTTP request. To set the port, use the SetWebSiteAndPorts method.

VBScript Syntax[VBScript]

[ lHTTPRedirectPort = ] FPCWebPublishingRule.HTTPRedirectPort

C++ Syntax[C++]

HRESULT get_HTTPRedirectPort(
  long *plHTTPRedirectPort
);

Parameters

lHTTPRedirectPort
Long value that specifies the port.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.IsDefault Property

Gets whether the rule is a preconfigured rule. A preconfigured rule cannot be deleted and it cannot have its order changed.

VBScript Syntax[VBScript]

[ bPreConfigured = ] FPCWebPublishingRule.IsDefault

C++ Syntax[C++]

HRESULT get_IsDefault(
  VARIANT_BOOL *pbPreConfigured

Parameters

bPreConfigured
Boolean value that specifies whether the rule is preconfigured.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Name Property

Gets or sets the name of the publishing rule. Names must be unique.

VBScript Syntax[VBScript]

FPCWebPublishingRule.Name [ = sName ]

C++ Syntax[C++]

HRESULT get_Name(
  BSTR *psName
);

HRESULT put_Name(
  BSTR sName
);

Parameters

sName
String that specifies the name of the rule.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.NonSecureProtocolRedirection Property

Gets or sets the protocol used when redirecting (bridging) a request that came on a nonsecure channel.

VBScript Syntax[VBScript]

FPCWebPublishingRule.NonSecureProtocolRedirection [ = PublishProtocolRedirectionType ]

C++ Syntax[C++]

HRESULT get_NonSecureProtocolRedirection(
  FpcPublishProtocolRedirectionType *pPublishProtocolRedirectionType
);

HRESULT put_NonSecureProtocolRedirection(
  FpcPublishProtocolRedirectionType PublishProtocolRedirectionType
);

Parameters

PublishProtocolRedirectionType
Protocol used when redirecting a request. It can have a value from the FpcPublishProtocolRedirectionType enumerated type.

The property is read-write.

Remarks

This property applies only when the Action property is set to fpcRouteRedirect.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Order Property

Gets the publishing rule's order of execution in relation to the other rules. The order can be modified by the MoveUp and MoveDown methods of the FPCWebPublishingRules collection. The order of the default rule cannot be changed from last.

VBScript Syntax[VBScript]

[ lOrder = ] FPCWebPublishingRule.Order

C++ Syntax[C++]

HRESULT get_Order(
  long *plOrder
);

Parameters

lOrder
Long value that specifies the order of execution.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCWebPublishingRule.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCWebPublishingRule.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SecureProtocolRedirection Property

Gets or sets the protocol used when redirecting (bridging) a request that came on a secure channel.

VBScript Syntax[VBScript]

FPCWebPublishingRule.SecureProtocolRedirection [ = PublishProtocolRedirectionType ]

C++ Syntax[C++]

HRESULT get_SecureProtocolRedirection(
  FpcPublishProtocolRedirectionType *pPublishProtocolRedirectionType
);

HRESULT put_SecureProtocolRedirection(
  FpcPublishProtocolRedirectionType PublishProtocolRedirectionType
);

Parameters

PublishProtocolRedirectionType
Protocol used when redirecting a request. It can have a value from the FpcPublishProtocolRedirectionType enumerated type.

The property is read-write.

Remarks

This property applies only when the Action property is set to fpcRouteRedirect.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SendOriginalHostHeader Property

Gets or sets whether ISA Server sends the original host header, or the header related to the site specified in the Web publishing rule. This property cannot be set through ISA Management.

VBScript Syntax[VBScript]

FPCWebPublishingRule.SendOriginalHostHeader [ = bSendOriginalHostHeader ]

C++ Syntax[C++]

HRESULT get_SendOriginalHostHeader(
  Variant_BOOL *pbSendOriginalHostHeader
);

HRESULT put_SendOriginalHostHeader(
  Variant_BOOL bSendOriginalHostHeader
);

Parameters

bSendOriginalHostHeader
Boolean that specifies whether the original host header is sent. The default value is FALSE, indicating that the header related to the site specified in the Web publishing rule is sent.

The property is read-write.

Example

The following VBScript script sets SendOriginalHostHeader to TRUE.

set objFPC=CreateObject("FPC.Root")
set rule = objFPC.arrays(1).Publishing.WebPublishingRules(1)
rule.SendOriginalHostHeader = true
rule.save

Remarks

ISA Server, by default, sends the host header corresponding to published sites, that is, the header related to the site specified in the publishing rule, rather than the original host header that ISA received. However, there are scenarios where the publishing servers rely on the host header to generate links on a page instead of generating relative links. These servers must receive the original host header which is recognized by the client. This property allows those servers to receive the original host header.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SetDestination Method

Sets the destinations to which the rule applies.

VBScript Syntax[VBScript]

FPCWebPublishingRule.SetDestination(DestType, sDestinationSet, ItemScope )

C++ Syntax[C++]

HRESULT SetDestination (
  FpcDestinationSelection DestType,
  BSTR sDestinationSet,
  FpcItemScope ItemScope
);

Parameters

DestType
Required. Defines the type of destinations. Can have a value of the FpcDestinationSelection enumerated type.
sDestinationSet
Optional. String that specifies a set of destinations to use. Only used if DestType equals fpcDestinationSet.
ItemScope
Value from the FpcItemScope enumerated type. Only used if DestType equals fpcDestinationSet. Specifies whether the destination set is one of an array's own policy elements or is an enterprise policy element. The default value is fpcArrayScope.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SetWebSiteAndPorts Method

Sets the action to Redirect and sets the redirect Web site and ports.

VBScript Syntax[VBScript]

FPCWebPublishingRule.SetWebSiteAndPorts(Action, sWebSite, lHTTPRedirectPort, lFTPRedirectPort, lSSLRedirectPort )

C++ Syntax[C++]

HRESULT SetWebSiteAndPorts (
  FpcPublishRouteType Action,
  BSTR sWebSite,
  long lHTTPRedirectPort,
  long lFTPRedirectPort,
  long lSSLRedirectPort
);

Parameters

Action
The FpcPublishRouteType value that indicates whether the Web publishing rule calls for redirection. If this has a value of fpcRouteDiscard, the sWebSite parameter should be set to an empty string. If this has a value of fpcRouteRedirect, the sWebSite parameter cannot be an empty string.
sWebSite
String value specifying the Web site to which to redirect. The default value for sWebSite is an empty string. If Action has a value of fpcRouteRedirect, the sWebSite parameter cannot be an empty string.
lHTTPRedirectPort
Long value specifying the HTTP redirect port. The default value is 80.
lFTPRedirectPort
Long value specifying the FTP redirect port. The default value is 21.
lSSLRedirectPort
Long value specifying the SSL redirect port. The default value is 443.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SSLClientCertificate Property

Gets or sets the client certificate to use when authenticating by using the publishing server.

VBScript Syntax[VBScript]

FPCWebPublishingRule.SSLClientCertificate [ = oFPCSSLCertificate ]

C++ Syntax[C++]

HRESULT get_SSLClientCertificate (
  IFPCSSLCertificate **ppoFPCSSLCertificate
);

HRESULT put_SSLClientCertificate (
  IFPCSSLCertificate *poFPCSSLCertificate
);

Parameters

oFPCSSLCertificate
Reference to an FPCSSLCertificate object.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SSLRedirectPort Property

Gets the port to redirect requests if redirecting as an SSL request. To set the port, use the SetWebSiteAndPorts method.

VBScript Syntax[VBScript]

[ lSSLRedirectPort = ] FPCWebPublishingRule.SSLRedirectPort

C++ Syntax[C++]

HRESULT get_SSLRedirectPort(
  long *plSSLRedirectPort
);

Parameters

lSSLRedirectPort
Long value that specifies the port.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.SSLRequireSecureChannel Property

Gets or sets whether a secure channel is required.

VBScript Syntax[VBScript]

FPCWebPublishingRule.SSLRequireSecureChannel [ = FpcSSLRequireSecureChannel ]

C++ Syntax[C++]

HRESULT get_SSLRequireSecureChannel(
  FpcSSLRequireSecureChannelMode *pFpcSSLRequireSecureChannel
);

HRESULT put_SSLRequireSecureChannel(
  FpcSSLRequireSecureChannelMode FpcSSLRequireSecureChannel
);

Parameters

FpcSSLRequireSecureChannel
Value from the FpcSSLRequireSecureChannelMode enumerated type.

The property is read-write.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.VendorParametersSets Property

Retrieves a reference to an object for storing and loading custom data into the FPCWebPublishingRule object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCWebPublishingRule.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebPublishingRule


FPCWebPublishingRule.WebSite Property

Gets the URL to redirect requests to when the Action property is set to fpcRouteRedirect.

VBScript Syntax[VBScript]

[ sWebSite = ] FPCWebPublishingRule.WebSite

C++ Syntax[C++]

HRESULT get_WebSite(
  BSTR *psWebSite
);

Parameters

sWebSite
String that specifies the URL of the Web site.

The property is read only. It can be set by using the SetWebSiteAndPorts method.

Applies To

FPCWebPublishingRule


FPCWebPublishingRules Collection

The FPCWebPublishingRules collection provides access to a group of FPCWebPublishingRule objects of an ISA server. The rules appear in the collection by their order of execution. The order can be modified by the MoveUp and MoveDown methods.

The FPCWebPublishingRules collection is a property of the FPCArrayPolicy object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCWebPublishingRules interface.

Methods

The following table lists the methods of the FPCWebPublishingRules collection.

Method | Description
Add | Creates a new FPCWebPublishingRule object in the list and returns a reference to it.
Item | Retrieves the given FPCWebPublishingRule object from the collection.
MoveDown | Moves the given rule down the ladder of execution.
MoveUp | Moves the given rule up the ladder of execution.
Refresh | Reads the collection's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Remove | Removes an FPCWebPublishingRule object from the collection.
Save | Saves the collection's configuration to persistent storage.

Properties

The following table lists the properties of the FPCWebPublishingRules collection.

Property | Description
Count | Gets the number of FPCWebPublishingRule objects in the collection.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCWebPublishingRules collection's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebPublishingRules.Add Method

Creates a new FPCWebPublishingRule object in the list and returns a reference to it.

Note If there are no listen entries configured using the FPCListenEntries.Add method, then ISA does not listen for incoming or outgoing Web requests.

VBScript Syntax[VBScript]

[ oFPCWebPublishingRule = ] FPCWebPublishingRules.Add( sName )

C++ Syntax[C++]

HRESULT Add(
  BSTR sName,
  IFPCWebPublishingRule **ppoFPCWebPublishingRule
);

Parameters

sName
Required. String that specifies the name of the new rule.

Return Value

oFPCWebPublishingRule
Reference to the FPCWebPublishingRule object.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Count Property

Gets the number of FPCWebPublishingRule objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCWebPublishingRules.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCWebPublishingRule objects.

The property is read-only.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Item Method

Retrieves the given FPCWebPublishingRule object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCWebPublishingRules.Item( vIndex )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vIndex,
  IFPCWebPublishingRule **pvItem
);

Parameters

vIndex
Required. Name or one-based index of the object to retrieve.

Return Value

vItem
If successful, returns a reference to an object of type FPCWebPublishingRule, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.MoveDown Method

Moves the given rule down the ladder of execution.

Note The order of the default rule cannot be changed from last.

VBScript Syntax[VBScript]

FPCWebPublishingRules.MoveDown( lIndex )

C++ Syntax[C++]

HRESULT MoveDown(
  long lIndex
);

Parameters

lIndex
Required. Index (current order) of the rule to move down.

Applies To

FPCWebPublishingRules

See Also

MoveUp


FPCWebPublishingRules.MoveUp Method

Moves the given rule up the ladder of execution.

Note The order of the default rule cannot be changed from last.

VBScript Syntax[VBScript]

FPCWebPublishingRules.MoveUp( lIndex )

C++ Syntax[C++]

HRESULT MoveUp(
  long lIndex
);

Parameters

lIndex
Required. Index (current order) of the rule to move up.

Applies To

FPCWebPublishingRules

See Also

MoveDown


FPCWebPublishingRules.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCWebPublishingRules.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Remove Method

Removes an FPCWebPublishingRule object from the collection.

VBScript Syntax[VBScript]

FPCWebPublishingRules.Remove( vItem )

C++ Syntax[C++]

HRESULT Remove(
  VARIANT vItem
);

Parameters

vItem
Required. Name or one-based index of the object to remove.

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCWebPublishingRules.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCWebPublishingRules


FPCWebPublishingRules.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCWebPublishingRules collection's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCWebPublishingRules.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebPublishingRules


FPCWebRequestConfiguration Object

The FPCWebRequestConfiguration object provides access to the properties of the incoming Web request /outgoing Web request configuration.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCWebRequestConfiguration interface.

Methods

The following table lists the methods of the FPCWebRequestConfiguration object.

Method | Description
Refresh | Reads the object's configuration information from persistent storage, discarding any changes to the configuration that were not saved.
Save | Saves the object's configuration to persistent storage.

Properties

The following table lists the properties of the FPCWebRequestConfiguration object.

Property | Description
AllInterfaces | Gets or sets whether the Web proxy listens on all the Internet Protocols (IPs) of the computer regardless of the list of entries.
AlwaysAuthenticate | Gets or sets whether the Web proxy always authenticates a request.
CacheSSLResponses | Gets or sets whether responses are cached when the incoming or outgoing request uses SSL.
ConnectionTimeout | Gets or sets the time-out of a connection.
NumberOfConnections | Gets or sets the number of connections.
ResolveInArray | Gets or sets a Boolean value that defines whether to try to get the URL from another member of the array, according to the CARP algorithm.
SSLPort | Gets or sets the SSL port.
TCPPort | Gets or sets the Transmission Control Protocol (TCP) port.
UnlimitedNumberOfConnections | Gets or sets whether the Web proxy has an unlimited number of connections.
VendorParametersSets | Gets a reference to an object for storing and loading custom data into the FPCWebRequestConfiguration object's storage.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebRequestConfiguration.AllInterfaces Property

Gets or sets whether the Web proxy listens on all the Internet Protocols (IPs) of the computer regardless of the list of entries.

VBScript Syntax[VBScript]

[ bAllInterfaces = ] FPCWebRequestConfiguration.AllInterfaces

C++ Syntax[C++]

HRESULT get_AllInterfaces(
  VARIANT_BOOL *pbAllInterfaces
);

HRESULT put_AllInterfaces(
  VARIANT_BOOL bAllInterfaces
);

Parameters

bAllInterfaces
Boolean value that specifies whether the Web proxy listens on all IP addresses of the ISA Server computer, regardless of the individual entries within this collection.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.AlwaysAuthenticate Property

Gets or sets whether the Web proxy always authenticates a request even when the policy check (through rules) does not require it. Setting this property to TRUE will ensure that the logs always contain the identity of a Web request originator.

For more information, see About Authentication in ISA Server.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.AlwaysAuthenticate [= bAlwaysAuthenticate ]

C++ Syntax[C++]

HRESULT get_AlwaysAuthenticate(
  VARIANT_BOOL *pbAlwaysAuthenticate
);

HRESULT put_AlwaysAuthenticate(
  VARIANT_BOOL bAlwaysAuthenticate
);

Parameters

bAlwaysAuthenticate
Boolean value. When set to TRUE, authentication is always enforced. When FALSE, authentication is disabled.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.CacheSSLResponses Property

Gets or sets whether responses are cached when either the incoming or outgoing request uses SSL. By default, caching is enabled when SSL is in use.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.CacheSSLResponses [ = bCacheSSL ]

C++ Syntax[C++]

HRESULT get_CacheSSLReponses(
  VARIANT_BOOL *pbCacheSSL
);

HRESULT put_CacheSSLReponses(
  VARIANT_BOOL bCacheSSL
);

Parameters

bCacheSSL
A Boolean value that determines whether SSL responses are cached. TRUE by default (responses are cached).

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.ConnectionTimeout Property

Gets or sets the time-out of a connection.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.ConnectionTimeout [ = lConnectionTimeout ]

C++ Syntax[C++]

HRESULT get_ConnectionTimeout(
  long *plConnectionTimeout
);

HRESULT put_ConnectionTimeout(
  long lConnectionTimeout
);

Parameters

lConnectionTimeout
Long value that specifies a time-out.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.NumberOfConnections Property

Gets or sets the number of simultaneous connections with the Internet. When UnlimitedNumberOfConnections is set to TRUE, this property is ignored.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.NumberOfConnections [ = lNumberOfConnections ]

C++ Syntax[C++]

HRESULT get_NumberOfConnections(
  long *plNumberOfConnections
);

HRESULT put_NumberOfConnections(
  long lNumberOfConnections
);

Parameters

lNumberOfConnections
Long value that specifies the number of connections with the Internet.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.Refresh Method

Reads all the items from persistent storage. When the Refresh method is called, any configuration changes made after the last Save method call will be lost.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.ResolveInArray Property

Gets or sets a Boolean value that defines how the object will get the requested URL. If the ResolveInArray property is set to FALSE, the object will try to get the URL from the current array. If the property is set to TRUE, the object will try to get the URL from another array by using the Cache Array Routing Protocol (CARP) algorithm.

Note This property is available only for an array in ISA Server Enterprise Edition. It is not available for a stand-alone server, or for ISA Server Standard Edition.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.ResolveInArray [ = bResolveInArray ]

C++ Syntax[C++]

HRESULT get_ResolveInArray(
  VARIANT_BOOL *pbResolveInArray
);

HRESULT put_ResolveInArray(
  VARIANT_BOOL bResolveInArray
);

Parameters

bResolveInArray
Boolean value that defines whether to try to get the URL from another member of the array.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.Save Method

Saves all configuration changes to persistent storage. It is important to remember that any changes made by scripts and programs are not saved until after the Save method is called.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.Save()

C++ Syntax[C++]

HRESULT Save();

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.SSLPort Property

Gets or sets the SSL port.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.SSLPort [ = lSSLPort ]

C++ Syntax[C++]

HRESULT get_SSLPort(
  long *plSSLPort
);

HRESULT put_SSLPort(
  long lSSLPort
);

Parameters

lSSLPort
Long value that specifies the SSL port.

The property is read-write.

Note When you change the SSL port, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.TCPPort Property

Gets or sets the Transmission Control Protocol (TCP) port.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.TCPPort [ = lTCPPort ]

C++ Syntax[C++]

HRESULT get_TCPPort(
  long *plTCPPort
);

HRESULT put_TCPPort(
  long lTCPPort
);

Parameters

lTCPPort
Long value that specifies TCP port.

The property is read-write.

Note When you change the TCP port, and have saved changes by using the Save method, the Web proxy (w3proxy) service must be restarted for your change to take effect. To stop and restart the Web proxy service, use the FPCArray.SendRestartNotification method.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.UnlimitedNumberOfConnections Property

Gets or sets whether the Web proxy has an unlimited number of connections.

VBScript Syntax[VBScript]

FPCWebRequestConfiguration.UnlimitedNumberOfConnections [ = bUnlimitedNumberOfConnections ]

C++ Syntax[C++]

HRESULT get_UnlimitedNumberOfConnections(
  VARIANT_BOOL *pbUnlimitedNumberOfConnections
);

HRESULT put_UnlimitedNumberOfConnections(
  VARIANT_BOOL bUnlimitedNumberOfConnections
);

Parameters

bUnlimitedNumberOfConnections
A Boolean value that specifies whether the Web proxy has an unlimited number of connections. When set to TRUE, the value of NumberOfConnections is ignored.

The property is read-write.

Applies To

FPCWebRequestConfiguration


FPCWebRequestConfiguration.VendorParametersSets Property

Gets a reference to an object for storing and loading custom data into the FPCWebRequestConfiguration object's storage.

VBScript Syntax[VBScript]

[ collFPCVendorParametersSets = ] FPCWebRequestConfiguration.VendorParametersSets

C++ Syntax[C++]

HRESULT get_VendorParametersSets(
  IFPCVendorParametersSets **pcollFPCVendorParametersSets
);

Parameters

collFPCVendorParametersSets
Reference to the FPCVendorParametersSets collection.

The property is read-only.

Applies To

FPCWebRequestConfiguration


FPCWebSession Object

The FPCWebSession object represents a single Web session of an ISA Server computer. A Web session is a period of time during which a computer requests Web objects from an ISA server.

Note FPCWebSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. An RPC call is used to query ISA services about its sessions because the information is dynamic.

This object is a member of the FPCWebSessions collection.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This object implements the IFPCWebSession interface.

Methods

The following table lists the methods of the FPCWebSession object.

Method | Description
AbortSession | Aborts the session using a remote procedure call (RPC), and removes the session from the collection.
Refresh | Reads the FPCWebSession objects using an RPC call.

Properties

The following table lists the properties of the FPCWebSession object.

Property | Description
ClientIpAddress | Gets the IP address of the client computer for this session.
UserName | Gets the user name for this session.
WebSessionAdditionalInfo | Gets a pointer to the FPCWebSessionAdditionalInfo object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebSession.AbortSession Method

Stops the session.

VBScript Syntax[VBScript]

FPCWebSession.AbortSession()

C++ Syntax[C++]

HRESULT AbortSession();

Applies To

FPCWebSession


FPCWebSession.ClientIpAddress Property

Gets the IP address of the client computer.

VBScript Syntax[VBScript]

[ sClientIpAddress = ] FPCWebSession.ClientIpAddress

C++ Syntax[C++]

HRESULT get_ClientIpAddress(
  BSTR *psClientIpAddress
);

Parameters

sClientIpAddress
String that specifies the IP address of the client computer.

The property is read-only.

Applies To

FPCWebSession


FPCWebSession.Refresh Method

Reads all properties of the FPCWebSession object from the Web proxy service by means of a remote procedure call (RPC).

VBScript Syntax[VBScript]

FPCWebSession.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Remarks

FPCWebSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. An RPC call is used to query ISA services about its sessions because the information is dynamic.

Applies To

FPCWebSession


FPCWebSession.UserName Property

Gets the client Windows NT/Windows 2000 account.

VBScript Syntax[VBScript]

[ sName = ] FPCWebSession.UserName

C++ Syntax[C++]

HRESULT get_UserName(
  BSTR *psName
);

Parameters

sName
String that specifies the Windows NT/Windows 2000 account of the client.

The property is read-only.

Applies To

FPCWebSession


FPCWebSession.WebSessionAdditionalInfo Property

Gets a reference to the FPCWebSessionAdditionalInfo object, which contains additional properties of the Web session.

VBScript Syntax[VBScript]

[ oFPCWebSessionAdditionalInfo = ] FPCWebSession.WebSessionAdditionalInfo

C++ Syntax[C++]

HRESULT get_WebSessionAdditionalInfo(
  IFPCWebSessionAdditionalInfo **poFPCWebSessionAdditionalInfo
);

Parameters

oFPCWebSessionAdditionalInfo
Reference to the FPCWebSessionAdditionalInfo object.

The property is read-only.


FPCWebSessions Collection

The FPCWebSessions collection provides access to a group of FPCWebSession objects. Each FPCWebSession object represents one Web session of an ISA Server computer. A Web session is a period of time during which a computer requests Web objects from an ISA server. This collection is a property of the FPCServer object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCWebSessions interface.

Methods

The following table lists the methods of the FPCWebSessions collection.

Method | Description
Item | Retrieves the given object from the collection.
Refresh | Reads all the objects using a remote procedure call (RPC).

Properties

The following table lists the properties of the FPCWebSessions collection.

Property | Description
Count | Gets the number of FPCWebSession objects in the collection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebSessions.Count Property

Gets the number of FPCWebSession objects in the collection.

VBScript Syntax[VBScript]

[ lCount = ] FPCWebSessions.Count

C++ Syntax[C++]

HRESULT get_Count(
  long *plCount
);

Parameters

lCount
Long value that specifies the number of FPCWebSession objects.

The property is read-only.

Applies To

FPCWebSessions


FPCWebSessions.Item Method

Retrieves the given FPCWebSession object from the collection.

VBScript Syntax[VBScript]

[ vItem = ] FPCWebSessions.Item( vUserOrIndex, vClientComputer )

C++ Syntax[C++]

HRESULT Item(
  VARIANT vUserOrIndex,
  VARIANT vClientComputer,
  IFPCWebSession **pvItem
);

Parameters

vUserOrIndex
Required. User name or one-based index of the object to retrieve.
vClientComputer
Optional. Client computer.

Return Value

vItem
If successful, returns a reference to an object of type FPCWebSession, otherwise:
  • In C++, returns an error code and a null object.
  • In scripting languages and in Visual Basic, an error is raised and can be intercepted by using an error handler.

Applies To

FPCWebSessions


FPCWebSessions.Refresh Method

Retrieves all the FPCWebSession objects from the Web proxy service by using a remote procedure call (RPC).

VBScript Syntax[VBScript]

FPCWebSessions.Refresh()

C++ Syntax[C++]

HRESULT Refresh();

Remarks

FPCWebSession is not a persistent object. There is no persistent storage for this object because its attributes are supplied at run time by ISA. An RPC call is used to query ISA services about its sessions because the information is dynamic.

Applies To

FPCWebSessions


FPCWebSessionAdditionalInfo Object

The FPCWebSessionAdditionalInfo object represents additional information about an FPCWebSession object. This object is a property of an FPCWebSession object.

Click here to see the ISA object hierarchy.

Note to C++ Programmers

This collection implements the IFPCWebSessionAdditionalInfo interface.

Properties

The following table lists the properties of the FPCWebSessionAdditionalInfo object.

Property | Description
ConnectionsNumber | Gets the number of requests for this session.
Duration | Gets the duration of the session.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FPCWebSessionAdditionalInfo.ConnectionsNumber Property

Gets the number of requests for a session.

VBScript Syntax[VBScript]

[ lConnectionsNumber = ] FPCWebSessionAdditionalInfo.ConnectionsNumber

C++ Syntax[C++]

HRESULT get_ConnectionsNumber(
  long *plConnectionsNumber
);

Parameters

lConnectionsNumber
Long value that specifies the number of requests.

The property is read-only.

Applies To

FPCWebSessionAdditionalInfo


FPCWebSessionAdditionalInfo.Duration Property

Gets the duration of the session.

VBScript Syntax[VBScript]

[ lDuration = ] FPCWebSessionAdditionalInfo.Duration

C++ Syntax[C++]

HRESULT get_Duration(
  long *plDuration
);

Parameters

lDuration
Long value that specifies the session duration.

The property is read-only.

Applies To

FPCWebSessionAdditionalInfo


Enumerated Types

This section describes the enumerated data values used by the Internet Security and Acceleration Server (ISA) administration COM objects. They are defined in Comenum.h.

  • FpcAccountTypes
  • FpcAceFlag
  • FpcAceFlagType
  • FpcAceType
  • FpcActionTypes
  • FpcActiveCachingPolicy
  • FpcAlertsAccessRights
  • FpcAppliesToContentMethodType
  • FpcAppliesToType
  • FpcArrayType
  • FpcAuthType
  • FpcBackupRouteType
  • FpcBackupType
  • FpcBrowserConfigScriptFlag
  • FpcCacheExpirationPolicy
  • FpcClientBackupRouteType
  • FpcComponents
  • FpcConnectionDirectionType
  • FpcConnectionProtocolType
  • FpcDestinationAddressType
  • FpcDestinationSelection
  • FpcDomainArrayObjAccessRights
  • FpcFetchUrlFlags
  • FpcFilterDirection
  • FpcFilterPriority
  • FpcFirewallServiceLogFields
  • FpcFwAccessByType
  • FpcFwForwardType
  • FpcGetIpsFlags
  • FpcIncludeStatus
  • FpcIndArrayObjAccessRights
  • FpcItemScope
  • FpcLoadSize
  • FpcLogFileDirectoryType
  • FpcLoggingComponents
  • FpcLogPeriod
  • FpcLogType
  • FpcNameSystem
  • FpcOperationModes
  • FpcPacketFiltersLogFields
  • FpcPfDirectionType
  • FpcPfFilterMode
  • FpcPfFilterStatusType
  • FpcPfFilterType
  • FpcPfIcmpCodeOptions
  • FpcPfIcmpTypeOptions
  • FpcPfLocalHostType
  • FpcPfLocalPortType
  • FpcPfProtocolType
  • FpcPfRemoteHostType
  • FpcPfRemotePortType
  • FpcPfUDPDirectionType
  • FpcPolicyUsed
  • FpcPrimaryRouteType
  • FpcProtocolRuleAction
  • FpcProtocolSelectionType
  • FpcPublishProtocolRedirectionType
  • FpcPublishRoute
  • FpcPublishRouteType
  • FpcRouteCacheAction
  • FpcRouteCacheContent
  • FpcRuleActions
  • FpcScheduleDays
  • FpcScheduledContentDownloadPeriod
  • FpcScheduleHours
  • FpcSDControl
  • FpcSDRevision
  • FpcSecurityScope
  • FpcServices
  • FpcSessionsAccessRights
  • FpcSSLClientCertificateMode
  • FpcSSLRequireSecureChannelMode
  • FpcTimeScale
  • FpcUDPConnectionDirectionType
  • FpcWebProxyServiceLogFields


FpcAccountTypes

The FpcAccountTypes enumerated type contains values that describe types of Microsoft® Windows NT® and Windows® 2000 accounts.

enum FpcAccountTypes {
  fpcAccountTypeUser,
  fpcAccountTypeGroup,
  fpcAccountTypeDomain,
  fpcAccountTypeAlias,
  fpcAccountTypeWellKnownGroup
};

Members

fpcAccountTypeUser (0)
A user.
fpcAccountTypeGroup (1)
A group of users.
fpcAccountTypeDomain (2)
A domain of users.
fpcAccountTypeAlias (3)
An alias.
fpcAccountTypeWellKnownGroup (4)
A predefined account such as "Everyone".

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAceFlag

The FpcAceFlag enumerated type contains values that specify how security may propagate along an inheritance path and how the system generates audit messages.

enum FpcAceFlag{
  fpcAceFlag_Inherit_Ace              = 0x2,
  fpcAceFlag_No_Propagate_Inherit_Ace = 0x4,
  fpcAceFlag_Inherit_Only_Ace         = 0x8,
  fpcAceFlag_Inherited_Ace            = 0x10,
  fpcAceFlag_Valid_Inherit_Flags      = 0x1f,
  fpcAceFlag_Successful_Access        = 0x40,
  fpcAceFlag_Failed_Access                = 0x80
};

Members

fpcAceFlag_Inherit_Ace
Child objects will inherit this access-control entry (ACE). The inherited ACE is inheritable unless the ADS_ACEFLAG_NO_PROPAGATE_INHERIT_ACE flag is set.
fpcAceFlag_No_Propagate_Inherit_Ace
ADSI will clear the ADS_ACEFLAG_INHERIT_ACE flag for the inherited ACEs of child objects. This prevents the ACE from being inherited by subsequent generations of objects.
fpcAceFlag_Inherit_Only_Ace
Indicates an inherit-only ACE that does not exercise access control on the object to which it is attached. If this flag is not set, the ACE is an effective ACE that exerts access control on the object to which it is attached.
fpcAceFlag_Inherited_Ace
Indicates whether or not the ACE was inherited. The system sets this bit.
fpcAceFlag_Valid_Inherit_Flags
Indicates whether the inherit flags are valid. The system sets this bit.
fpcAceFlag_Successful_Access
Generates audit messages for successful access attempts. Used with ACEs that audit the system in a system access-control list (SACL).
fpcAceFlag_Failed_Access
Generates audit messages for failed access attempts. Used with ACEs that audit the system in a SACL.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAceFlagType

The FpcAceFlagType enumerated type contains values that indicate the presence of the ObjectType or InheritedObjectType fields in the access-control entry (ACE).

enum FpcAceFlagType{
  fpcAceFlagType_Object_Type_Present           = 0x1,
  fpcAceFlagType_Inherited_Object_Type_Present = 0x2
};

Members

fpcAceFlagType_Object_Type_Present
The ObjectType field is present in the ACE, but InheritedObjectType is not.
fpcAceFlagType_Inherited_Object_Type_Present
The InheritedObjectType field is present in the ACE, but ObjectType is not.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAceType

The FpcAceType enumerated type contains values that specify types of access-control entries (ACE).

enum FpcAceType{
  fpcAceType_Access_Allowed        = 0,
  fpcAceType_Access_Denied         = 0x1,
  fpcAceType_System_Audit          = 0x2,
  fpcAceType_Access_Allowed_Object = 0x5,
  fpcAceType_Access_Denied_Object  = 0x6,
  fpcAceType_System_Audit_Object   = 0x7
}FpcAceType;

Members

fpcAceType_Access_Allowed
The ACE is of the standard ACCESS ALLOWED type, where the ObjectType and InheritedObjectType fields are NULL.
fpcAceType_Access_Denied
The ACE is of the standard ACCESS_DENIED type, where the ObjectType and InheritedObjectType fields are NULL.
fpcAceType_System_Audit
The ACE is of the standard system type, where the ObjectType and InheritedObjectType fields are NULL.
fpcAceType_Access_Allowed_Object
The ACE is of the ADSI extension of the ACCESS ALLOWED type, where either ObjectType or InheritedObjectType or both contain a GUID.
fpcAceType_Access_Denied_Object
The ACE is of the ADSI extension of the ACCESS_DENIED type, where either ObjectType or InheritedObjectType or both contain a GUID.
fpcAceType_System_Audit_Object
The ACE is of the ADSI extension of the system type, where either ObjectType or InheritedObjectType or both contain a GUID.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcActionTypes

The FpcActionTypes enumerated type contains values that describe types of action that events can trigger.

enum FpcActionTypes {
  fpcAlertActionLogEvent,
  fpcAlertActionCommand,
  fpcAlertActionSendMail,
  fpcAlertActionStopServices,
  fpcAlertActionStartServices
};

Members

fpcAlertActionLogEvent
Logs events to the system event log.
fpcAlertActionCommand
Runs a specified command.
fpcAlertActionSendMail
Sends a mail message.
fpcAlertActionStopServices
Stops ISA services.
fpcAlertActionStartServices
Starts ISA services.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcActiveCachingPolicy

The FpcActiveCachingPolicy enumerated type contains values that describe the behavior of the active caching mechanism.

enum FpcActiveCachingPolicy {
  fpcActiveCachingEmphasizeOnFewerNetworkAccesses,
  fpcActiveCachingNoEmphasize,
  fpcActiveCachingEmphasizeOnFasterUserResponse
};

Members

fpcActiveCachingEmphasizeOnFewerNetworkAccesses
Less active caching is initiated.
fpcActiveCachingNoEmphasize
Average caching behavior is used.
fpcActiveCachingEmphasizeOnFasterUserResponse
More active caching is initiated.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAlertsAccessRights

The FpcAlertsAccessRights enumerated type contains values that specify the access rights for alerts.

FpcAlertsAccessRights {
  fpcAlertsRight_Delete                 = 0x10000,
  fpcAlertsRight_Read_Control           = 0x20000,
  fpcAlertsRight_Write_Dac              = 0x40000,
  fpcAlertsRight_Write_Owner            = 0x80000,
  fpcAlertsRight_Synchronize            = 0x100000,
  fpcAlertsRight_Access_System_Security = 0x1000000,
  fpcAlertsRight_Generic_Read           = 0x80000000,
  fpcAlertsRight_Generic_Write          = 0x40000000,
  fpcAlertsRight_Generic_Execute        = 0x20000000,
  fpcAlertsRight_Generic_All            = 0x10000000,
  fpcAlertsRight_Read                   = 0x00000001,
  fpcAlertsRight_Reset                  = 0x00000002
};

Members

fpcAlertsRight_Delete
The right to delete the object.
fpcAlertsRight_Read_Control
The right to read the information in the object's security descriptor, not including the information in the system access control list (SACL).
fpcAlertsRight_Write_Dac
The right to modify the discretionary access-control list (DACL) in the object's security descriptor.
fpcAlertsRight_Write_Owner
The right to change the owner in the object's security descriptor.
fpcAlertsRight_Synchronize
The right to use the object for synchronization. This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.
fpcAlertsRight_Access_System_Security
Access to the system security.
fpcAlertsRight_Generic_Read
Read access.
fpcAlertsRight_Generic_Write
Write access.
fpcAlertsRight_Generic_Execute
Execute access.
fpcAlertsRight_Generic_All
Read, write, and execute access.
fpcAlertsRight_Read
The right to read the monitoring alerts information.
fpcAlertsRight_Reset
The right to reset each alert.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAppliesToContentMethodType

The FpcAppliesToContentMethodType enumerated type contains values that identify the type of content used in a rule.

enum FpcAppliesToContentMethodType {
  fpcAppliesToAllContent,
  fpcAppliesToSpecifiedContent
};

Members

fpcAppliesToAllContent
Rule applies to all types of content.
fpcAppliesToSpecifiedContent
Rule applies to specified content.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAppliesToType

The FpcAppliesToType enumerated type contains values that describe types of request origins to which a rule applies.

enum FpcAppliesToType {
  fpcAppliesToAll,
  fpcAppliesToUsers,
  fpcAppliesToClientSets
};

Members

fpcAppliesToAll
Applies to all requests regardless of origin.
fpcAppliesToUsers
Applies to requests from specified users.
fpcAppliesToClientSets
Applies to requests from specified computers.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcArrayType

The FpcArrayType enumerated type contains values that identify whether an array is an stand-alone server or a shared array.

enum FpcArrayType {
  fpcTypeStandardEdition
  fpcTypeStandAlone,
  fpcTypeArray
};

Members

fpcTypeStandardEdition
Array is a stand-alone (registry based) server with a single server in an ISA Server standard edition configuration.
fpcTypeStandAlone
Array is a stand-alone (registry-based) server with a single server.
fpcTypeArray
Array is an Active Directory Service-based array with an unlimited number of servers.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcAuthType

The FpcAuthType enumerated type contains values that describe authentication methods used for inter-server connections.

enum FpcAuthType {
  fpcUiAuthBasic,
  fpcUiAuthNtlm
};

Members

fpcUiAuthBasic
Basic authentication.
fpcUiAuthNtlm
Windows NT Challenge/Response authentication.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcBackupRouteType

The FpcBackupRouteType enumerated type contains values that determine the backup route type.

enum FpcBackupRouteType {
  fpcBackupRouteNone,
  fpcBackupRouteDirect,
  fpcBackupRouteUpstream
};

Members

fpcBackupRouteNone
There is no backup route.
fpcBackupRouteDirect
Backup route is direct to the specified destination
fpcBackupRouteUpstream
Backup route is through an upstream proxy server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcBackupType

The FpcBackupType enumerated type contains values that determine the type of backup.

enum FpcBackupType {
  fpcBackupArrayConfiguration,
  fpcBackupEnterpriseConfiguration
}

Members

fpcBackupArrayConfiguration
The backup will be for an array configuration.
fpcBackupEnterpriseConfiguration
The backup will be for an enterprise configuration.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcBrowserConfigScriptFlag

The FpcBrowserConfigScriptFlag enumerated type provides flags that determine the type of browser configuration script.

enum FpcBrowserConfigScriptFlag {
  fpcBrowserDefaultScript,
  fpcBrowserCustomScript
};

Members

fpcBrowserDefaultScript
Use the default script.
fpcBrowserCustomScript
Use the custom script.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcCacheExpirationPolicy

The FpcCacheExpirationPolicy enumerated type contains values that define how soon cached Web pages expire.

enum FpcCacheExpirationPolicy {
  fpcCachePolicyCustom,
  fpcCachePolicyEmphasizeMoreUpdates,
  fpcCachePolicyNoEmphasize,
  fpcCachePolicyEmphasizeMoreCacheHits
};

Members

fpcCachePolicyCustom
Custom policy.
fpcCachePolicyEmphasizeMoreUpdates
Cached objects expire more quickly.
fpcCachePolicyNoEmphasize
Average behavior.
fpcCachePolicyEmphasizeMoreCacheHits
Cached objects live longer.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcClientBackupRouteType

The FpcClientBackupRouteType enumerated type contains values that determine the client backup route type.

enum FpcClientBackupRouteType {
  fpcClientBackupRouteDirectToInternet,
  fpcClientBackupRouteViaProxy
};

Members

fpcClientBackupRouteDirectToInternet
Client backup route is direct to the Internet.
fpcClientBackupRouteViaProxy
Client backup route is through an upstream proxy server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcComponents

The FpcComponents enumerated type contains values that specify the components installed on an array.

enum FpcComponents {
  fpcNoComponents       =0,
  fpcPacketFiltering    =1,
  fpcNAT                =2,
  fpcWebProxy           =4,
  fpcHTTPTransparent    =8,
  fpcGenericFwProtocols =16,
  fpcFirewallExtensions =32,
  fpcAllComponents      =255
};

Members

fpcNoComponents
No components.
fpcPacketFiltering (1)
Packet filtering.
fpcNAT (2)
SecureNAT.
fpcWebProxy (4)
Web proxy.
fpcHTTPTransparent (8)
Firewall service.
fpcGenericFwProtocols (16)
Generic firewall protocols.
fpcFirewallExtensions (32)
Firewall extensions (application filters).
fpcAllComponents (255)
All ISA components.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcConnectionDirectionType

The FpcConnectionDirectionType enumerated type contains values that describe the type of Firewall service connection.

enum FpcConnectionDirectionType {
  fpcInbound,
  fpcOutbound
};

Members

fpcInbound
Inbound connection.
fpcOutbound
Outbound connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcConnectionProtocolType

The FpcConnectionProtocolType enumerated type contains values that describe the connection protocol.

enum FpcConnectionProtocolType {
  fpcTCP,
  fpcUDP
};

Members

fpcTCP
Transmission Control Protocol (TCP).
fpcUDP
User Datagram Protocol (UDP).

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcDestinationAddressType

The FpcDestinationAddressType enumerated type contains values that describe the type of destination.

enum FpcDestinationAddressType {
  fpcDestinationTypeDomain,
  fpcDestinationTypeSingleIp,
  fpcDestinationTypeIpRange
};

Members

fpcDestinationTypeDomain
Destination defined by domain name.
fpcDestinationTypeSingleIp
Destination defined by single Internet Protocol (IP) address.
fpcDestinationTypeIpRange
Destination defined by an IP range.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcDestinationSelection

The FpcDestinationSelection enumerated type contains values that describe the type of destinations referred to in a rule.

enum FpcDestinationSelection {
  fpcAllDestinations,
  fpcAllInternalDestinations,
  fpcAllExternalDestinations,
  fpcSpecifiedDestinationSet,
  fpcAllExceptDestinationSet
};

Members

fpcAllDestinations
All destinations.
fpcAllInternalDestinations
All internal destinations.
fpcAllExternalDestinations
All external destinations.
fpcSpecifiedDestinationSet
Destinations that are part of a specified set.
fpcAllExceptDestinationSet
All destinations except those in the specified destination set.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcDomainArrayObjAccessRights

The FpcDomainArrayObjAccessRights enumerated type defines the access rights for an array object. These access rights are mapped to Active Directory access rights.

enum FpcDomainArrayObjAccessRights{
  fpcDomainArrayObjRight_Delete                 = 0x10000,
  fpcDomainArrayObjRight_Read_Control           = 0x20000,
  fpcDomainArrayObjRight_Write_Dac              = 0x40000,
  fpcDomainArrayObjRight_Write_Owner            = 0x80000,
  fpcDomainArrayObjRight_Synchronize            = 0x100000,
  fpcDomainArrayObjRight_Access_System_Security = 0x1000000,
  fpcDomainArrayObjRight_Generic_Read           = 0x80000000,
  fpcDomainArrayObjRight_Generic_Write          = 0x40000000,
  fpcDomainArrayObjRight_Generic_Execute        = 0x20000000,
  fpcDomainArrayObjRight_Generic_All            = 0x10000000,
  fpcDomainArrayObjRight_Create_Child           = 0x00000001,
  fpcDomainArrayObjRight_Delete_Child           = 0x00000002,
  fpcDomainArrayObjRight_List_Childred          = 0x00000004,
  fpcDomainArrayObjRight_Self                   = 0x00000008,
  fpcDomainArrayObjRight_Read_Prop              = 0x00000010,
  fpcDomainArrayObjRight_Write_Prop             = 0x00000020,
  fpcDomainArrayObjRight_Delete_Tree            = 0x00000040,
  fpcDomainArrayObjRight_List_Object            = 0x00000080,
  fpcDomainArrayObjRight_Control_Access         = 0x00000100
};

Members

fpcDomainArrayObjRight_Delete
The right to delete the object.
fpcDomainArrayObjRight_Read_Control
The right to read information from the security descriptor of the object, not including the information in the SACL.
fpcDomainArrayObjRight_Write_Dac
The right to modify the discretionary access-control list (DACL) in the object's security descriptor.
fpcDomainArrayObjRight_Write_Owner
The right to assume ownership of the object. The user must be a trustee of the object. The user cannot transfer the ownership to other users.
fpcDomainArrayObjRight_Synchronize
The right to use the object for synchronization. This enables a thread to wait until the object is in the signaled state.
fpcDomainArrayObjRight_Access_System_Security
The right to get or set the SACL in the object's security descriptor.
fpcDomainArrayObjRight_Generic_Read
The right to read from the security descriptor, examine the object as well as its children, and read all properties.
fpcDomainArrayObjRight_Generic_Write
The right to write all the properties and write to the DACL. The user can add and remove the object to and from the directory.
fpcDomainArrayObjRight_Generic_Execute
The right to list children of this object.
fpcDomainArrayObjRight_Generic_All
The right to create or delete children, delete a subtree, read and write properties, examine children and the object itself, add and remove the object from the directory, and read or write with an extended right.
fpcDomainArrayObjRight_Create_Child
The right to create children of the object. The ObjectType member of an access control entry (ACE) can contain a GUID that identifies the type of child object whose creation is being controlled. If ObjectType does not contain a GUID, the ACE controls the creation of all child object types.
fpcDomainArrayObjRight_Delete_Child
The right to delete children of the object. The ObjectType member of an ACE can contain a GUID that identifies a type of child object whose deletion is being controlled. If ObjectType does not contain a GUID, the ACE controls the deletion of all child object types.
fpcDomainArrayObjRight_List_Childred
The right to list children of this object.
fpcDomainArrayObjRight_Self
The right to modify the group membership of a group object.
fpcDomainArrayObjRight_Read_Prop
The right to read properties of the object. The ObjectType member of an ACE can contain a GUID that identifies a property set or property. If ObjectType does not contain a GUID, the ACE controls the right to read all of the object's properties.
fpcDomainArrayObjRight_Write_Prop
The right to write properties of the object. The ObjectType member of an ACE can contain a GUID that identifies a property set or property. If ObjectType does not contain a GUID, the ACE controls the right to write all of the object's properties.
fpcDomainArrayObjRight_Delete_Tree
The right to delete all children of this object, regardless of the permission on the children.
fpcDomainArrayObjRight_List_Object
The right to list a particular object. If the user is not granted such a right, the object is hidden from the user.
fpcDomainArrayObjRight_Control_Access
The right to perform an operation controlled by an extended access right. The ObjectType member of an ACE can contain a GUID that identifies the extended right. If ObjectType does not contain a GUID, the ACE controls the right to perform all extended right operations associated with the object.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFetchUrlFlags

The FpcFetchUrlFlags enumerated type contains flags that control FetchUrl method behavior.

enum FpcFetchUrlFlags {
  fpcFetchTtlIfNone,
  fpcFetchTtlOverride,
  fpcFetchSynchronous,
  fpcFetchNoArrayRouting,
  fpcFetchForceCache
};

Members

fpcFetchTtlIfNone
The TtlInMinutes parameter should be used only if the object does not contain an "Expires" or "Cache-Control: maximum-age" HTTP header.
fpcFetchTtlOverride
The TtlInMinutes parameter takes precedence over any HTTP headers in the object.
fpcFetchSynchronous
Method will not return until the fetch is completed.
fpcFetchNoArrayRouting
Fetches on a target server even if another array member is the preferred location.
fpcFetchForceCache
Caches even if object cannot normally be cached.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFilterDirection

The FpcFilterDirection enumerated type contains values that describe whether a filter operates in forward reverse, or both modes.

enum FpcFilterDirection {
  fpcFilterDirectionForward,
  fpcFilterDirectionReverse,
  fpcFilterDirectionBoth
};

Members

fpcFilterDirectionForward
Filter applies to incoming packets.
fpcFilterDirectionReverse
Filter applies to outgoing packets.
fpcFilterDirectionBoth
Filter applies to incoming and outgoing packets.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFilterPriority

The FpcFilterPriority enumerated type defines Web filter priority.

enum FpcFilterPriority {
  fpcFilterPriority_Low,
  fpcFilterPriority_Medium,
  fpcFilterPriority_High
};

Members

fpcFilterPriority_Low
Filter has low priority.
fpcFilterPriority_Medium
Filter has medium priority.
fpcFilterPriority_High
Filter has high priority.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFirewallServiceLogFields

The FpcFirewallServiceLogFields enumerated type contains values that describe the log fields of the Firewall service.

enum FpcFirewallServiceLogFields {
  fpcFWClientIP           = 0x0000001,
  fpcFWClientUserName     = 0x0000002,
  fpcFWClientAgent        = 0x0000004,
  fpcFWClientAuthenticate = 0x0000008,
  fpcFWLogDate            = 0x0000010,
  fpcFWLogTime            = 0x0000020,
  fpcFWService            = 0x0000040,
  fpcFWServerName         = 0x0000080,
  fpcFWReferredServer     = 0x0000100,
  fpcFWDestHost           = 0x0000200,
  fpcFWDestHostIP         = 0x0000400,
  fpcFWDestHostPort       = 0x0000800,
  fpcFWProcessingTime     = 0x0001000,
  fpcFWBytesSent          = 0x0002000,
  fpcFWBytesRecvd         = 0x0004000,
  fpcFWProtocol           = 0x0008000,
  fpcFWTransport          = 0x0010000,
  fpcFWOperation          = 0x0020000,
  fpcFWUri                = 0x0040000,
  fpcFWMimeType           = 0x0080000,
  fpcFWObjectSource       = 0x0100000,
  fpcFWResultCode         = 0x0200000,
  fpcFWCacheInfo          = 0x0400000,
  fpcFWRule1              = 0x0800000,
  fpcFWRule2              = 0x1000000,
  fpcFWSessionId          = 0x2000000,
  fpcFWConnectionId       = 0x4000000
};

Members

fpcFWClientIP
The client IP field.
fpcFWClientUserName
The client user name field.
fpcFWClientAgent
The client agent field.
fpcFWClientAuthenticate
The client authentication field.
fpcFWLogDate
The date field.
fpcFWLogTime
The time field.
fpcFWService
The service field.
fpcFWServerName
The server name field.
fpcFWReferredServer
The referred server field.
fpcFWDestHost
The destination host field.
fpcFWDestHostIP
The destination host IP field.
fpcFWDestHostPort
The destination host port field.
fpcFWProcessingTime
The processing time field.
fpcFWBytesSent
The bytes sent field.
fpcFWBytesRecvd
The bytes received field.
fpcFWProtocol
The protocol field.
fpcFWTransport
The transport field.
fpcFWOperation
The operation field.
fpcFWUri
The Uniform Resource Identifier field.
fpcFWMimeType
The mime type field.
fpcFWObjectSource
The object source field.
fpcFWResultCode
The result code field.
fpcFWCacheInfo
The cache information field.
fpcFWRule1
A rule field.
fpcFWRule2
A rule field.
fpcFWSessionId
The session ID field.
fpcFWConnectionId
The connection ID field.


FpcFwAccessByType

The FpcFwAccessByType enumerated type contains values that describe how to represent the connection between the Firewall client and the Firewall service.

enum FpcFwAccessByType {
  fpcClientAccessSetByIp,
  fpcClientAccessSetByName
};

Members

fpcClientAccessSetByIp
Identifies by IP address.
fpcClientAccessSetByName
Identifies by name.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcFwForwardType

The FpcFwForwardType enumerated type specifies the mode of proxy forwarding.

typedef enum FpcFwForwardType {
  fpcPrimaryConnection,
  fpcChaining
};

Members

fpcPrimaryConnection
Forward requests to primary connection.
fpcChaining
Forward requests to another chaining proxy server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcGetIpsFlags

The FpcGetIpsFlags enumerated type contains values that specify internal or external IP addresses.

enum FpcGetIpsFlags {
  fpcInternalOnly,
  fpcExternalOnly,
  fpcInternalAndExternal
};

Members

fpcInternalOnly
Internal IPs only.
fpcExternalOnly
External IPs only.
fpcInternalAndExternal
Both internal and external.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcIncludeStatus

The FpcIncludeStatus enumerated type defines whether an account is included in or excluded from the list of accounts to which a rule applies.

enum FpcIncludeStatus {
  fpcInclude,
  fpcExclude
};

Members

fpcInclude
Account is included.
fpcExclude
Account is excluded.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcIndArrayObjAccessRights

The FpcIndArrayObjAccessRights enumerated type defines the access rights for a stand-alone server object. These access rights are mapped to registry access rights.

enum FpcIndArrayObjAccessRights{
  fpcIndArrayObjRight_Delete                 = 0x10000,
  fpcIndArrayObjRight_Read_Control           = 0x20000,
  fpcIndArrayObjRight_Write_Dac              = 0x40000,
  fpcIndArrayObjRight_Write_Owner            = 0x80000,
  fpcIndArrayObjRight_Synchronize            = 0x100000,
  fpcIndArrayObjRight_Access_System_Security = 0x1000000,
  fpcIndArrayObjRight_Generic_Read           = 0x80000000,
  fpcIndArrayObjRight_Generic_Write          = 0x40000000,
  fpcIndArrayObjRight_Generic_Execute        = 0x20000000,
  fpcIndArrayObjRight_Generic_All            = 0x10000000,
  fpcIndArrayObjRight_Query_Value            = 0x0001,
  fpcIndArrayObjRight_Set_Value              = 0x0002,
  fpcIndArrayObjRight_Create_Sub_Key         = 0x0004,
  fpcIndArrayObjRight_Enum_Sub_Keys          = 0x0008,
  fpcIndArrayObjRight_Notify                 = 0x0010,
  fpcIndArrayObjRight_Create_Link            = 0x0020
};

Members

fpcIndArrayObjRight_Delete
The right to delete the object.
fpcIndArrayObjRight_Read_Control
The right to read the information in the object's security descriptor, not including the information in the system access control list (SACL).
fpcIndArrayObjRight_Write_Dac
The right to modify the discretionary access-control list (DACL) in the object's security descriptor.
fpcIndArrayObjRight_Write_Owner
The right to change the owner in the object's security descriptor.
fpcIndArrayObjRight_Synchronize
The right to use the object for synchronization.
fpcIndArrayObjRight_Access_System_Security
Access to the system security.
fpcIndArrayObjRight_Generic_Read
Read access.
fpcIndArrayObjRight_Generic_Write
Write access.
fpcIndArrayObjRight_Generic_Execute
Execute access.
fpcIndArrayObjRight_Generic_All
Read, write, and execute access.
fpcIndArrayObjRight_Query_Value
Required to query a value of a registry-key.
fpcIndArrayObjRight_Set_Value
Required to create or set a value of a registry-key.
fpcIndArrayObjRight_Create_Sub_Key
Required to create a subkey of a registry-key.
fpcIndArrayObjRight_Enum_Sub_Keys
Required to enumerate the subkeys of a registry-key.
fpcIndArrayObjRight_Notify
Required to request change notifications for a registry key or for subkeys of a registry key.
fpcIndArrayObjRight_Create_Link
Required to create a link to a registry key.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcItemScope

The FpcItemScope enumerated type specifies the scope of the item. FpcItemScope designates whether the item has array-level scope or enterprise-level scope. This enumerated type is used for policy elements such as protocols, destination sets, schedules, and so forth.

enum FpcItemScope {
  fpcArrayScope,
  fpcEnterpriseScope
};

Members

fpcArrayScope
Item has array-level scope.
fpcEnterpriseScope
Item has enterprise-level scope.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLoadSize

The FpcLoadSize enumerated type contains values that describe the Web proxy load size.

enum FpcLoadSize {
  fpcLoadSize_Small,
  fpcLoadSize_Medium,
  fpcLoadSize_Large
};

Members

fpcLoadSize_Small
Small load size.
fpcLoadSize_Medium
Medium load size.
fpcLoadSize_Large
Large load size.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLogFileDirectoryType

The FpcLogFileDirectoryType enumerated type contains values that describe the path type for the log file.

enum FpcLogFileDirectoryType {
  fpcFullPath,
  fpcRelativePath
};

Members

fpcFullPath
The directory of the log files is given in full path.
fpcRelativePath
The directory of the log files is relative to the ISA Install directory.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLoggingComponents

The FpcLoggingComponents enumerated type contains values that describe the type of logging component.

enum FpcLoggingComponents {
  fpcProxyWebLog,
  fpcProxyFwLog,
  fpcProxyPacketFiltersLog
};

Members

fpcProxyWebLog
The Web proxy log.
fpcProxyFwLog
The Firewall service log.
fpcProxyPacketFiltersLog
Packet filters log.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLogPeriod

The FpcLogPeriod enumerated type contains values that describe the period of time before starting a new text log file.

enum FpcLogPeriod {
  FpcLogDaily =1,
  FpcLogWeekly,
  FpcLogMonthly,
  FpcLogYearly
};

Members

FpcLogDaily
One log file per day.
FpcLogWeekly
One log file per week.
FpcLogMonthly
One log file per month.
FpcLogYearly
One log file per year.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcLogType

The FpcLogType enumerated type contains values that describe the logging method.

enum FpcLogType {
  fpcFile_EXT_Format,
  fpcFile_ISA_Format,
  fpcODBC
};

Members

fpcFile_EXT_Format
Logging the World Wide Web Consortium (W3C) extended format to text log files.
fpcFile_ISA_Format
Logging the ISA format to text log files.
fpcODBC
Logging to the open database connectivity (ODBC) log.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcNameSystem

The FpcNameSystem enumerated type contains values that describe the name system used for CARP hashing.

enum FpcNameSystem {
  fpcNameSystem_DNS,
  fpcNameSystem_WINS
};

Members

fpcNameSystem_DNS
Use the Domain Name System (DNS).
fpcNameSystem_WINS
Use the Windows Internet Name Service (WINS) name system.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcOperationModes

The FpcOperationModes enumerated type contains values that describe alerting operation modes.

enum FpcOperationModes {
  fpcCountThreshold,
  fpcRateThreshold,
  fpcIntervalThreshold
};

Members

fpcCountThreshold
Events count before re-raising alert.
fpcRateThreshold
Minimal rate of events per second for raising alert.
fpcIntervalThreshold
Minimal interval in minutes before re-raising alert.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPacketFiltersLogFields

The FpcPacketFiltersLogFields enumerated type contains values that describe the log fields for packet filters.

enum FpcPacketFiltersLogFields {
  fpcPFLogDate          = 0x0001,
  fpcPFLogTime          = 0x0002,
  fpcSourceAddress      = 0x0004,
  fpcDestinationAddress = 0x0008,
  fpcProtocol           = 0x0010,
  fpcParam1             = 0x0020,
  fpcParam2             = 0x0040,
  fpcTcpFlags           = 0x0080,
  fpcFilterRule         = 0x0100,
  fpcInterface          = 0x0200,
  fpcIPHeader           = 0x0400,
  fpcPayload            = 0x0800
};

Members

fpcPFLogDate
The date field.
fpcPFLogTime
The time field.
fpcSourceAddress
The source address field.
fpcDestinationAddress
The destination address field.
fpcProtocol
The protocol field.
fpcParam1
A parameter field.
fpcParam2
A parameter field.
fpcTcpFlags
The TCP flags field.
fpcFilterRule
The filter rule field.
fpcInterface
The interface field.
fpcIPHeader
The IP header field.
fpcPayload
The payload field.


FpcPfDirectionType

The FpcPfDirectionType enumerated type contains values that describe packet directions.

enum FpcPfDirectionType {
  fpcPfDirectionIndexIn,
  fpcPfDirectionIndexOut,
  fpcPfDirectionIndexBoth
};

Members

fpcPfDirectionIndexIn (1)
In direction.
fpcPfDirectionIndexOut (2)
Out direction.
fpcPfDirectionIndexBoth (3)
Both directions (in and out).

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfFilterMode

The FpcPfFilterMode enumerated type contains values that describe the type of packet filter, either allowing or blocking.

enum FpcPfFilterMode {
  fpcAllowingPacketFilter,
  fpcBlockingPacketFilter
};

Members

fpcAllowingPacketFilter (1)
A regular packet filter that allows the packets to pass.
fpcBlockingPacketFilter (2)
A blocking filter that drops packets that match the filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfFilterStatusType

The FpcPfFilterStatusType enumerated contains values that describe packet-filter status.

enum FpcPfFilterStatusType {
  fpcFilterNotChanged,
  fpcFilterWasAdded,
  fpcFilterWasRemoved,
  fpcFilterWasChanged
};

Members

fpcFilterNotChanged (1)
No changes occurred in the filter.
fpcFilterWasAdded
A packet filter was added.
fpcFilterWasRemoved
A packet filter was removed.
fpcFilterWasChanged
A packet filter was changed.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfFilterType

The FpcPfFilterType enumerated type contains values that describe packet filter types.

enum FpcPfFilterType {
  fpcCustomFilterType,
  fpcDnsLookupPredefinedType,
  fpcIcmpAllOutboundPredefinedType,
  fpcIcmpPingResponsePredefinedType,
  fpcIcmpPingQueryPredefinedType,
  fpcIcmpSrcQuenchPredefinedType,
  fpcIcmpTimeoutPredefinedType,
  fpcIcmpUnreachablePredefinedType,
  fpcPptpCallPredefinedType,
  fpcPptpReceivePredefinedType,
  fpcSmtpPredefinedType,
  fpcPop3PredefinedType,
  fpcIdentdPredefinedType,
  fpcHttpServerPredefinedType,
  fpcHttpsServerPredefinedType,
  fpcNetbiosWinsClientPredefinedType,
  fpcNetbiosAllPredefinedType
};

Members

fpcCustomFilterType (1)
A custom filter with options set by the user. Custom filter options can also be seen through ISA Management.
fpcDnsLookupPredefinedType (2)
Describes the Domain Name System (DNS) lookup predefined static filter.
fpcIcmpAllOutboundPredefinedType (3)
Describes the Internet Control Message Protocol (ICMP) outbound predefined static filter.
fpcIcmpPingResponsePredefinedType (4)
Describes the ICMP ping response predefined static filter.
fpcIcmpPingQueryPredefinedType (5)
Describes the ICMP ping query predefined static filter.
fpcIcmpSrcQuenchPredefinedType (6)
Describes the ICMP source quench predefined static filter.
fpcIcmpTimeoutPredefinedType (7)
Describes the ICMP timeout predefined static filter.
fpcIcmpUnreachablePredefinedType (8)
Describes the ICMP unreachable predefined static filter.
fpcPptpCallPredefinedType (9)
Describes the PPTP call predefined static filter.
fpcPptpReceivePredefinedType (10)
Describes the PPTP receive predefined static filter.
fpcSmtpPredefinedType (11)
Describes the SMTP receive predefined static filter.
fpcPop3PredefinedType (12)
Describes the POP3 predefined static filter.
fpcIdentdPredefinedType (13)
Describes the identified predefined static filter.
fpcHttpServerPredefinedType (14)
Describes the HTTP server predefined static filter.
fpcHttpsServerPredefinedType (15)
Describes the HTTPS server predefined static filter.
fpcNetbiosWinsClientPredefinedType (16)
Describes the Netbios WINS predefined static filter.
fpcNetbiosAllPredefinedType (17)
Describes the Netbios all predefined static filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfIcmpCodeOptions

The FpcPfIcmpCodeOptions enumerated type represents Internet Control Message Protocol (ICMP) code options used by the IP packet filter.

enum FpcPfIcmpCodeOptions {
  fpcPfAnyIcmpCode,
  fpcPfFixedIcmpCode
};

Members

fpcPfAnyIcmpCode (1)
Any ICMP code.
fpcPfFixedIcmpCode (2)
Fixed ICMP code.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfIcmpTypeOptions

The FpcPfIcmpTypeOptions enumerated type represents Internet Control Message Protocol (ICMP) type options used by the IP packet filter.

enum FpcPfIcmpTypeOptions {
  fpcPfAnyIcmpType,
  fpcPfFixedIcmpType
};

Members

fpcPfAnyIcmpType (1)
Any ICMP type.
fpcPfFixedIcmpType (2)
Fixed ICMP type.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfLocalHostType

The FpcPfLocalHostType enumerated type contains values that describe the type of local host used by the packet filter.

enum FpcPfLocalHostType {
  fpcPfDefaultProxyExternalIp,
  fpcPfSpecificProxyIp,
  fpcPfInternalComputer,
  fpcPfInternalIPRange
};

Members

fpcPfDefaultProxyExternalIp (1)
No host specified (default external IP).
fpcPfSpecificProxyIp (2)
Proxy IP specified.
fpcPfInternalComputer (3)
Internal computer specified.
fpcPfInternalIPRange (4)
A range of internal IPs.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfLocalPortType

The FpcPfLocalPortType enumerated type represents the port options used by the packet filter.

enum FpcPfLocalPortType {
  fpcPfAnyPort,
  fpcPfFixedPort,
  fpcPfDynamicPort
};

Members

fpcPfAnyPort (1)
Any port.
fpcPfFixedPort (2)
Fixed port (followed by port number).
fpcPfDynamicPort (3)
Dynamic port (1024-5000).

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfProtocolType

The FpcPfProtocolType enumerated type contains values that describe predefined static packet filters' Internet Protocol (IP) ports.

enum FpcPfProtocolType {
  fpcPfAnyProtocolIpIndex,
  fpcPfIcmpProtocolIpIndex,
  fpcPfTcpProtocolIpIndex,
  fpcPfUdpProtocolIpIndex
};

Members

fpcPfAnyProtocolIpIndex (0)
Any protocol.
fpcPfIcmpProtocolIpIndex (1)
Internet Control Message Protocol (ICMP) protocol.
fpcPfTcpProtocolIpIndex (6)
Translation Control Protocol (TCP) protocol.
fpcPfUdpProtocolIpIndex (17)
User Datagram Protocol (UDP) protocol.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfRemoteHostType

The FpcPfRemoteHostType enumerated type contains values that describe the remote host type used by the packet filter.

enum FpcPfRemoteHostType {
  fpcPfAnyHost,
  fpcPfSingleHost,
  fpcPfExternalIpRange
};

Members

fpcPfAnyHost (1)
Any host possible.
fpcPfSingleHost
Single host specified.
fpcPfExternalIpRange
A range of external IPs.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfRemotePortType

The FpcPFRemotePortType enumerated type contains values that describe packet filter port-type options.

enum FpcPfRemotePortType {
  fpcPfAnyRemotePort,
  fpcPfFixedRemotePort
};

Members

fpcPfAnyRemotePort (1)
Any port.
fpcPfFixedRemotePort
Fixed port (followed by port number).

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPfUDPDirectionType

The FpcPfUDPDirectionType enumerated type contains values that describe UDP packet directions.

enum FpcPfUDPDirectionType {
  fpcPfUDPDirectionReceiveOnly,
  fpcPfUDPDirectionSendOnly,
  fpcPfDirectionBoth,
  fpcPfDirectionReceiveSend,
  fpcPfDirectionSendReceive
};

Members

fpcPfUDPDirectionReceiveOnly (1)
Receive the packets.
fpcPfUDPDirectionSendOnly (2)
Send the packets.
fpcPfDirectionBoth (3)
Send and receive packets.
fpcPfDirectionReceiveSend (4)
Receive packets and send on the same port.
fpcPfDirectionSendReceive (5)
Send packets and receive on the same port.


FpcPolicyUsed

The FpcPolicyUsed enumerated type specifies whether the array uses array policy, enterprise policy, or both policies.

enum FpcPolicyUsed {
  fpcArrayPolicyUsed,
  fpcEnterprisePolicyUsed,
  fpcArrayAndEnterprisePoliciesUsed
};

Members

fpcArrayPolicyUsed
Uses array policy only.
fpcEnterprisePolicyUsed
Uses enterprise policy only.
fpcArrayAndEnterprisePoliciesUsed
Uses array and enterprise policies.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPrimaryRouteType

The FpcPrimaryRouteType enumerated type provides values that determine the primary route type.

enum FpcPrimaryRouteType {
  fpcPrimaryRouteDirect,
  fpcPrimaryRouteUpstream,
  fpcPrimaryRouteAlternate
};

Members

fpcPrimaryRouteDirect
Sends request directly to the requested destination.
fpcPrimaryRouteUpstream
Sends request to an upstream ISA server or array.
fpcPrimaryRouteAlternate
Routes the request to any other server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcProtocolRuleAction

The FpcProtocolRuleAction enumerated type contains values that describe the types of actions performed by the protocol rules.

enum FpcProtocolRuleAction {
  fpcActionAllow,
  fpcActionDeny
};

Members

fpcActionAllow
Allows Internet Protocol (IP) connection requests.
fpcActionDeny
Denies IP connection requests.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcProtocolSelectionType

The FpcProtocolSelectionType enumerated type contains values that describe type of protocols to which a protocol rule applies.

enum FpcProtocolSelectionType {
  fpcAllIpTraffic,
  fpcSpecifiedProtocols,
  fpcAllExceptSpecifiedProtocols
};

Members

fpcAllIpTraffic
All Internet Protocol (IP) connections.
fpcSpecifiedProtocols
Protocols specified by the SpecifiedProtocols property.
fpcAllExceptSpecifiedProtocols
All IPs except the specified protocols.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPublishProtocolRedirectionType

The FpcPublishProtocolRedirectionType enumerated type contains values that describe the protocol chosen when redirecting a Web request.

enum FpcPublishProtocolRedirectionType {
  fpcHTTP,
  fpcFTP,
  fpcSSL
};

Members

fpcHTTP
The request is routed using the HTTP protocol.
fpcFTP
The request is routed using the FTP protocol.
fpcSSL
The request is routed using the SSL protocol.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPublishRoute

The FpcPublishRoute enumerated type contains values that describe options for Web publishing rules.

enum FpcPublishRoute {
  fpcRouteDiscard,
  fpcRouteRedirect
};

Members

fpcRouteDiscard
Discard the request.
fpcRouteRedirect
Redirect the request.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcPublishRouteType

The FpcPublishRouteType enumerated type contains values that describethe type of action performed by a publishing rule.

enum FpcPublishRouteType {
  fpcRouteDiscard,
  fpcRouteRedirect
};

Members

fpcRouteDiscard
Denies the desired access.
fpcRouteRedirect
Redirects the request to another computer.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcRouteCacheAction

The FpcRouteCacheAction enumerated type contains values that describe situations in which the proxy uses the cache rather than performing the routing action specified in a routing rule.

enum FpcRouteCacheAction {
  fpcServeFromCacheIfValidObjectExists,
  fpcServeFromCacheIfObjectExists,
  fpcServeFromCacheOnly
};

Members

fpcServeFromCacheIfValidObjectExists
Uses valid cached objects; otherwise, connects to the Internet to get a new version of it.
fpcServeFromCacheIfObjectExists
Uses object from cache (regardless of validity). If it does not exist, connects to the Internet.
fpcServeFromCacheOnly
Uses object from cache (regardless of validity). If it doesn't exist, it returns an error page, but does not connect to the Internet.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcRouteCacheContent

The FpcRouteCacheContent enumerated type contains values that describe the conditions under which a response will be cached.

enum FpcRouteCacheContent{
  fpcCacheAlways,
  fpcCacheOnlyIfNotDynamic,
  fpcNeverCache
} FpcRouteCacheContent;

Members

fpcCacheAlways
The response is always cached, even if the request or response headers indicate that the response should not be cached.
fpcCacheOnlyIfNotDynamic
The response is cached only if the headers indicate that the response should be cached.
fpcNeverCache
The response is never cached.


FpcRuleActions

The FpcRuleActions enumerated type contains values that describe actions performed when a rule criterion is met.

enum FpcRuleActions {
  fpcRuleActionPermit,
  fpcRuleActionDeny,
  fpcRuleActionRedirect
};

Members

fpcRuleActionPermit
Permits access to the requested Web page.
fpcRuleActionDeny
Denies access to the requested Web page.
fpcRuleActionRedirect
Redirects to a specific Web page.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcScheduleDays

The FpcScheduleDays enumerated type contains values that describe the days of the week. Used in schedule templates.

enum FpcScheduleDays {
  fpcALL_WEEK=-1,
  fpcSUN=0,
  fpcMON=1,
  fpcTUE=2,
  fpcWED=3,
  fpcTHU=4,
  fpcFRI=5,
  fpcSAT=6
};

Members

fpcALL_WEEK=-1
All days in week.
fpcSUN=0
Sunday.
fpcMON=1
Monday.
fpcTUE=2
Tuesday.
fpcWED=3
Wednesday.
fpcTHU=4
Thursday.
fpcFRI=5
Friday.
fpcSAT=6
Saturday.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcScheduledContentDownloadPeriod

The FpcScheduledContentDownloadPeriod enumerated type contains values that describe prefetching periods.

enum FpcScheduledContentDownloadPeriod {
  fpcDownloadOnce,
  fpcDownloadDaily,
  fpcDownloadSpecifiedDaysOfWeek
};

Members

fpcDownloadOnce (0)
One fetch only.
fpcDownloadDaily (1)
One fetch per day.
fpcDownloadSpecifiedDaysOfWeek (2)
One fetch per each specified day of week.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcScheduleHours

The FpcScheduleHours enumerated type contains values that describe the hours of the day. Used in schedule templates.

enum FpcScheduleHours {
  fpcALL_DAY=-1,
  fpcAM_0,
  fpcAM_1,
  fpcAM_2,
  fpcAM_3,
  fpcAM_4,
  fpcAM_5,
  fpcAM_6,
  fpcAM_7,
  fpcAM_8,
  fpcAM_9,
  fpcAM_10,
  fpcAM_11,
  fpcAM_12,
  fpcPM_1,
  fpcPM_2,
  fpcPM_3,
  fpcPM_4,
  fpcPM_5,
  fpcPM_6,
  fpcPM_7,
  fpcPM_8,
  fpcPM_9,
  fpcPM_10,
  fpcPM_11
};

Members

fpcALL_DAY=-1
All hours of the day.
fpcAM_0
Midnight.
fpcAM_1
1 A.M.
fpcAM_2
2 A.M.
fpcAM_3
3 A.M.
fpcAM_4
4 A.M.
fpcAM_5
5 A.M.
fpcAM_6
6 A.M.
fpcAM_7
7 A.M.
fpcAM_8
8 A.M.
fpcAM_9
9 A.M.
fpcAM_10
10 A.M.
fpcAM_11
11 A.M.
fpcAM_12
12 A.M.
fpcPM_1
1 P.M.
fpcPM_2
2 P.M.
fpcPM_3
3 P.M.
fpcPM_4
4 P.M.
fpcPM_5
5 P.M.
fpcPM_6
6 P.M.
fpcPM_7
7 P.M.
fpcPM_8
8 P.M.
fpcPM_9
9 P.M.
fpcPM_10
10 P.M.
fpcPM_11
11 P.M.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSDControl

The FpcSDControl enumerated type contains values that specify control flags for a security descriptor.

enum FpcSDControl{
  fpcSD_Control_Se_Owner_Defaulted       = 0x1,
  fpcSD_Control_Se_Group_Defaulted       = 0x2,
  fpcSD_Control_Se_Dacl_Present          = 0x4,
  fpcSD_Control_Se_Dacl_Defaulted        = 0x8,
  fpcSD_Control_Se_Sacl_Present          = 0x10,
  fpcSD_Control_Se_Sacl_Defaulted        = 0x20,
  fpcSD_Control_Se_Dacl_Auto_Inherit_Req = 0x100,
  fpcSD_Control_Se_Sacl_Auto_Inherit_Req = 0x200,
  fpcSD_Control_Se_Dacl_Auto_Inherited   = 0x400,
  fpcSD_Control_Se_Sacl_Auto_Inherited   = 0x800,
  fpcSD_Control_Se_Dacl_Protected        = 0x1000,
  fpcSD_Control_Se_Sacl_Protected        = 0x2000,
  fpcSD_Control_Se_Self_Relative         = 0x8000
};

Members

fpcSD_Control_Se_Owner_Defaulted
A default mechanism provides the owner security identifier (SID) of the security descriptor rather than the original provider of the security descriptor.
fpcSD_Control_Se_Group_Defaulted
A default mechanism provides the group SID of the security descriptor rather than the original provider of the security descriptor.
fpcSD_Control_Se_Dacl_Present
The discretionary access-control list (DACL) is present in the security descriptor. If this flag is not set, or if this flag is set and the DACL is NULL, the security descriptor allows full access to everyone.
fpcSD_Control_Se_Dacl_Defaulted
The security descriptor uses a default DACL built from the creator's access token.
fpcSD_Control_Se_Sacl_Present
The system access-control list (SACL) is present in the security descriptor.
fpcSD_Control_Se_Sacl_Defaulted
The security descriptor uses a default SACL built from the creator's access token.
fpcSD_Control_Se_Dacl_Auto_Inherit_Req
THE DACL of the security descriptor must be inherited.
fpcSD_Control_Se_Sacl_Auto_Inherit_Req
The SACL of the security descriptor must be inherited.
fpcSD_Control_Se_Dacl_Auto_Inherited
The DACL of the security descriptor supports automatic propagation of inheritable access-control entries (ACEs) to existing child objects.
fpcSD_Control_Se_Sacl_Auto_Inherited
The SACL of the security descriptor supports automatic propagation of inheritable ACEs to existing child objects.
fpcSD_Control_Se_Dacl_Protected
The security descriptor will not allow inheritable ACEs to modify the DACL.
fpcSD_Control_Se_Sacl_Protected
The security descriptor will not allow inheritable ACEs to modify the SACL.
fpcSD_Control_Se_Self_Relative
The security descriptor is of self-relative format with all the security information in a continuous block of memory.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSDRevision

The FpcSDRevision enumerated type contains values that specify the revision number of the access-control entry (ACE) or the access-control list (ACL).

enum FpcSDRevision{
  fpcSD_Revision = 4
};

Members

fpcSD_Revision
The revision number of the ACE, or the ACL, for Active Directory.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSecurityScope

The FpcSecurityScope enumerated type contains values that specify at what the level the security descriptor applies.

enum FpcSecurityScope {
  fpcEnterprisePoliciesScope,
  fpcEnterprisePolicyScope,
  fpcSingleArrayScope,
  fpcAlertsScope,
  fpcSessionsScope
};

Members

fpcEnterprisePoliciesScope
The security descriptor applies on the enterprise policies level.
fpcEnterprisePolicyScope
The security descriptor applies on the level of a single enterprise policy.
fpcSingleArrayScope
The security descriptor applies on the level of a single array.
fpcAlertsScope
The security descriptor applies to alerts.
fpcSessionsScope
The security descriptor applies to sessions.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcServices

The FpcServices enumerated type assigns numerical values for various components of ISA.

enum FpcServices {
  fpcFwSrvSvc,
  fpcW3ProxySvc,
  fpcAllServices
};

Members

fpcFwSrvSvc
The Firewall service component.
fpcW3ProxySvc
The Web proxy service component.
fpcAllServices
All the above values combined using the OR operator.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSessionsAccessRights

The FpcSessionsAccessRights enumerated type contains values that specify access rights for sessions.

enum FpcSessionsAccessRights {
  fpcSessionsRight_Delete                 = 0x10000,
  fpcSessionsRight_Read_Control           = 0x20000,
  fpcSessionsRight_Write_Dac              = 0x40000,
  fpcSessionsRight_Write_Owner            = 0x80000,
  fpcSessionsRight_Synchronize            = 0x100000,
  fpcSessionsRight_Access_System_Security = 0x1000000,
  fpcSessionsRight_Generic_Read           = 0x80000000,
  fpcSessionsRight_Generic_Write          = 0x40000000,
  fpcSessionsRight_Generic_Execute        = 0x20000000,
  fpcSessionsRight_Generic_All            = 0x10000000,
  fpcSessionsRight_Read                   = 0x00000001,
  fpcSessionsRight_Stop                   = 0x00000002
};

Members

fpcSessionsRight_Delete
The right to delete the object.
fpcSessionsRight_Read_Control
The right to read the information in the object's security descriptor, not including the information in the system access control list (SACL).
fpcSessionsRight_Write_Dac
The right to modify the discretionary access-control list (DACL) in the object's security descriptor.
fpcSessionsRight_Write_Owner
The right to change the owner in the object's security descriptor.
fpcSessionsRight_Synchronize
The right to use the object for synchronization. This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.
fpcSessionsRight_Access_System_Security
Access to the system security.
fpcSessionsRight_Generic_Read
Read access.
fpcSessionsRight_Generic_Write
Write access.
fpcSessionsRight_Generic_Execute
Execute access.
fpcSessionsRight_Generic_All
Read, write, and execute access.
fpcSessionsRight_Read
The right to read the session information.
fpcSessionsRight_Stop
The right to stop any session.

f


FpcSSLClientCertificateMode

The FpcSSLClientCertificateMode enumerated type contains values that describe Web-publishing rule parameters defining if client certification is allowed, ignored, or required.

enum FpcSSLClientCertificateMode {
  fpcSSLIgnoreClientCertificate,
  fpcSSLAcceptClientCertificate,
  fpcSSLRequireClientCertificate
};

Members

fpcSSLIgnoreClientCertificate
Client certificate is ignored.
fpcSSLAcceptClientCertificate
Client certificate is accepted.
fpcSSLRequireClientCertificate
Client certificate is required.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcSSLRequireSecureChannelMode

The FpcSSLRequireSecureChannelMode enumerated type contains values that describe Web-publishing rule parameters that defining whether an SSL connection is required and, if so, the type of connection.

enum FpcSSLRequireSecureChannelMode {
  fpcSSLDontRequireSecureChannel,
  fpcSSLRequireSecureChannel,
  fpcSSLRequire128BitSecureChannel
};

Members

fpcSSLDontRequireSecureChannel
Doesn't require secure channel.
fpcSSLRequireSecureChannel
Requires secure channel.
fpcSSLRequire128BitSecureChannel
Requires secure channel using 128-bit encryption.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcTimeScale

The FpcTimeScale enumerated type contains values that describe time ranges used in cache interval units.

enum FpcTimeScale {
  fpcTimeInSeconds =1,
  fpcTimeInMinutes,
  fpcTimeInHours,
  fpcTimeInDays,
  fpcTimeInWeeks
};

Members

fpcTimeInSeconds
Time in seconds.
fpcTimeInMinutes
Time in minutes.
fpcTimeInHours
Time in hours.
fpcTimeInDays
Time in days.
fpcTimeInWeeks
Time in weeks.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Msfpccom.idl.


FpcUDPConnectionDirectionType

The FpcUDPConnectionDirectionType enumerated type contains values that describe the type of UDP connection.

enum FpcUDPConnectionDirectionType {
  fpcReceiveOnly,
  fpcSendOnly,
  fpcReceiveSend,
  fpcSendReceive
};

Members

fpcReceiveOnly
Receive only.
fpcSendOnly
Send only.
fpcReceiveSend
Receive and then send.
fpcSendReceive
Send and then receive.


FpcWebProxyServiceLogFields

The FpcWebProxyServiceLogFields enumerated type contains values that describe the log fields of the Web proxy service.

enum FpcWebProxyServiceLogFields {
  fpcW3PClientIP           = 0x0000001,
  fpcW3PClientUserName     = 0x0000002,
  fpcW3PClientAgent        = 0x0000004,
  fpcW3PClientAuthenticate = 0x0000008,
  fpcW3PLogDate            = 0x0000010,
  fpcW3PLogTime            = 0x0000020,
  fpcW3PService            = 0x0000040,
  fpcW3PServerName         = 0x0000080,
  fpcW3PReferredServer     = 0x0000100,
  fpcW3PDestHost           = 0x0000200,
  fpcW3PDestHostIP         = 0x0000400,
  fpcW3PDestHostPort       = 0x0000800,
  fpcW3PProcessingTime     = 0x0001000,
  fpcW3PBytesSent          = 0x0002000,
  fpcW3PBytesRecvd         = 0x0004000,
  fpcW3PProtocol           = 0x0008000,
  fpcW3PTransport          = 0x0010000,
  fpcW3POperation          = 0x0020000,
  fpcW3PUri                = 0x0040000,
  fpcW3PMimeType           = 0x0080000,
  fpcW3PObjectSource       = 0x0100000,
  fpcW3PResultCode         = 0x0200000,
  fpcW3PCacheInfo          = 0x0400000,
  fpcW3PRule1              = 0x0800000,
  fpcW3PRule2              = 0x1000000,
};

Members

fpcW3PClientIP
The client IP field.
fpcW3PClientUserName
The client user name field.
fpcW3PClientAgent
The client agent field.
fpcW3PClientAuthenticate
The client authentication field.
fpcW3PLogDate
The date field.
fpcW3PLogTime
The time field.
fpcW3PService
The service field.
fpcW3PServerName
The server name field.
fpcW3PReferredServer
The referred server field.
fpcW3PDestHost
The destination host field.
fpcW3PDestHostIP
The destination host IP field.
fpcW3PDestHostPort
The destination host port field.
fpcW3PProcessingTime
The processing time field.
fpcW3PBytesSent
The bytes sent field.
fpcW3PBytesRecvd
The bytes received field
fpcW3PProtocol
The protocol field.
fpcW3PTransport
The transport field.
fpcW3POperation
The operation field.
fpcW3PUri
The Uniform Resource Identifier field.
fpcW3PMimeType
The mime type field.
fpcW3PObjectSource
The object source field.
fpcW3PResultCode
The result code field
fpcW3PCacheInfo
The cache information field.
fpcW3PRule1
A rule field.
fpcW3PRule2
A rule field.


Log Fields

You can use the Microsoft Internet Security and Acceleration (ISA) Server log to monitor and analyze status for the Firewall and Web proxy services and for packet filters. This section provides tables that list the fields you can include in each of the ISA Server log files.

Topics included in this section are:

  • Firewall and Web Proxy Log Fields
  • Packet Filter Log Fields


Firewall and Web Proxy Log fields

The following table lists the Firewall and Web proxy log fields.

Field Position | Descriptive Name (Field Name) | Description
1 | Client IP (c-ip) | The Internet protocol (IP) address of the requesting client.
2 | Client user name (cs-username) | Account of the user making the request. If ISA Server Access Control is not being used, ISA Server uses Anonymous.
3 Client agent (c-agent) The client application type sent by the client in the Hypertext Transfer Protocol (HTTP) header. When ISA Server is actively caching, the client agent is ISA Server.

For Firewall service, this field includes information about the client's operating system. See Operating system values.
4 | Authentication status (sc-authenticated) | Indicates whether or not client has been authenticated with the ISA Server. Possible values are Y and N.
5 | Date (date) | The date that the logged event occurred.
6 | Time (time) | The time that the logged event occurred. In W3C format, this is in Greenwich mean time.
7 | Service name (s-sitename) | The name of the service that is logged. w3proxy indicates outgoing Web requests to the Web proxy service. fwsrv indicates the Firewall service. w3reverseproxy indicates incoming Web requests to the Web proxy service
8 | Proxy name (s-computername) | The name of the computer running ISA Server. This is the computer name assigned in Windows 2000.
9 | Referring server name (cs-referred) | If ISA Server is used upstream in a chained configuration, this indicates the server name of the downstream server that sent the request.
10 | Destination name (r-host) | The domain name for the remote computer that provides service to the current connection. For the Web proxy service, a hyphen (-) in this field may indicate that an object was retrieved from the Web proxy server cache and not from the destination.
11 | Destination IP (r-ip) | The network IP address for the remote computer that provides service to the current connection. For the Web proxy service, a hyphen (-) in this field may indicate that an object was sourced from the Web proxy server cache and not from the destination. One exception is negative caching. In that case, this field indicates a destination IP address for which a negative-cached object was returned.
12 | Destination port (r-host) | The reserved port number on the remote computer that provides service to the current connection. This is used by the client application initiating the request.
13 Processing time (time-taken) This indicates the total time, in milliseconds, that is needed by ISA Server to process the current connection. It measures elapsed server time from the time that the server first received the request to the time when final processing occurred on the server—when results were returned to the client and the connection was closed.

For cache requests that were processed through the Web proxy service, processing time measures the elapsed server time needed to fully process a client request and return an object from the server cache to the client.
14 | Bytes sent (sc-bytes) | The number of bytes sent from the internal client to the external server during the current connection. A hyphen (-), a zero (0), or a negative number in this field indicates that this information was not provided by the remote computer or that no bytes were sent to the remote computer.
15 | Bytes received (cs-bytes) | The number of bytes sent from the external computer and received by the client during the current connection. A hyphen (-), a zero (0), or a negative number in this field indicates that this information was not provided by the remote computer or that no bytes were received from the external computer.
16 | Protocol name (cs-protocol) | Specifies the application protocol used for the connection. Common values are HTTP, FTP, Gopher, and Secure Hypertext Transfer protocol (HTTPS).
17 | Transport (cs-transport) | Specifies the transport protocol used for the connection. Common values are Transmission Control Protocol (TCP) and User Datagram Protocol (UDP).
18 Operation (s-operation) Specifies the application method used. For Web Proxy, common values are GET, PUT, POST, and HEAD.

For Firewall service, common values are CONNECT, BIND, SEND, RECEIVE, GHBN (GetHostByName), and GHBA (GetHostByAddress).
19 | Object name (cs-url) | For the Web proxy service, this field shows the contents of the URL request. This field applies onlyt to the Web proxy service log.
20 | Object MIME (cs-mime-type) | The Multipurpose Internet Mail Extensions (MIME) type for the current object. This field may also contain a hyphen (-) to indicate that this field is not used or that a valid MIME type was not defined or supported by the remote computer. This field applies only to the Web Proxy service log.
21 | Object source (s-object-source) | Indicates the source that was used to retrieve the current object. A table of some possible values is provided in Object source values.
22 | Result code (sc-status) | This field can be used to indicate a Windows (Win32) error code (for values less than 100), an HTTP status code (for values between 100 and 1,000), or a Winsock error code (for values between 10,000 and 11,004). A table of some possible values is provided in Result code values.
23 | Cache info (s-cache-info) | This number reflects the cache status of the object, which indicates why the object was or was not cached. This field applies only to the Web proxy service log. A table of some possible values is provided in Cache info values.
24 Rule #1 (rule#1) This reflects the rule that either allowed or denied access to the request, as follows:
  • If an outgoing request is allowed, this field reflects the protocol rule that allowed the request.
  • If an outgoing request is denied by a protocol rule, this field reflects the protocol rule.
  • If an outgoing request is denied by a site and content rule, this field reflects the protocol rule that would have allowed the request.
  • If an incoming request was denied, this field reflects the Web publishing or server publishing rule that denied the request.
  • If no rule specifically allowed the outgoing or incoming request, the request is denied. In this case, the field is empty.
25 Rule #2 (rule#2) This reflects the second rule that either allowed or denied access to the request.
  • If an outgoing request is allowed, this field reflects the site and content rule that allowed the request.
  • If an outgoing request is denied by a site and content rule, this field reflects the site and content rule that denied the request.
  • If no rule specifically allowed the outgoing or incoming request, the request is denied. In this case, the field is empty.
26 | Session ID (sessionid) | This identifies a session's connections. For Firewall clients, each process that connects through the Firewall service initiates a session. For secure network address translation (SecureNAT) clients, a single session is opened for all the connections that originate from the same IP address. This field is not included in the Web Proxy service log. This field applies only to the Firewall service log.
27 | Connection ID (connectionid) | This identifies entries that belong to the same socket. Outbound TCP usually has two entries for each connection: when the connection is established and when the connection is terminated. UDP usually has two entries for each remote address. This field is not included in the Web Proxy service log. This field applies only to the Firewall service log.

Object source values

Source values | Description
0 | No source information is available.
Cache | Source is the cache. Object returned from cache.
Inet | Source is the Internet. Object added to cache.
Member | Returned from another array member.
NotModified | Source is the cache. Client performed an If-Modified-Since request and object had not been modified.
NVCache | Source is the cache. Object could not be verified to source.
Upstream | Object returned from an upstream proxy cache.
Vcache | Source is the cache. Object was verified to source and had not been modified.
VFInet | Source is the Internet. Cached object was verified to source and had been modified.

Result code values

Value | Description
200 | OK - Successful connection.
201 | Created.
202 | Accepted.
204 | No content.
301 | Moved permanently.
302 | Moved temporarily.
304 | Not modified.
400 | Bad request.
401 | Unauthorized.
403 | Forbidden.
404 | Not found.
500 | Internal server error.
501 | Not implemented.
502 | Bad gateway.
503 | Service unavailable.
10060 | Connection timed out.
10061 | Connection refused by destination.
10065 | Host unreachable.
11001 | Host not found.

Cache info values

Value | Description
0x00000001 | Request should not be served from the cache.
0x00000002 | Request includes the IF-MODIFIED-SINCE header.
0x00000004 | Request includes one of these headers: CACHE-CONTROL:NO-CACHE or PRAGMA:NO-CACHE.
0x00000008 | Request includes the AUTHORIZATION header.
0x00000010 | Request includes the VIA header.
0x00000020 | Request includes the IF-MATCH header.
0x00000040 | Request includes the RANGE header.
0x00000080 | Request includes the CACHE-CONTROL: NO-STORE header.
0x00000100 | Request includes the CACHE-CONTROL: MAX-AGE, or CACHE-CONTROL: MAX-STALE or CACHE-CONTROL: MIN-FRESH header.
0x00000200 | Cache could not be updated.
0x00000400 | IF-MODIFIED-SINCE time specified in the request is newer than cached LASTMODIFIED time.
0x00000800 | Request includes the CACHE-CONTROL: ONLY-IF-CACHED header.
0x00001000 | Request includes the IF-NONE-MATCH header.
0x00002000 | Request includes the IF-UNMODIFIED-SINCE header.
0x00004000 | Request includes the IF-RANGE header.
0x00008000 | More than one VARY header.
0x00010000 | Response includes the CACHE-CONTROL: PUBLIC header.
0x00020000 | Response includes the CACHE-CONTROL: PRIVATE header.
0x00040000 | Response includes the CACHE-CONTROL: NO-CACHE or PRAGMA: NO-CACHE header.
0x00080000 | Response includes the CACHE-CONTROL: NO-STORE header.
0x00100000 | Response includes either the CACHE-CONTROL: MUST-REVALIDATE or CACHE-CONTROL: PROXY-REVALIDATE header.
0x00200000 | Response includes the CACHE-CONTROL: MAX-AGE or S-MAXAGE header.
0x00400000 | Response includes the VARY header.
0x00800000 | Response includes the LAST-MODIFIED header.
0x01000000 | Response includes the EXPIRES header.
0x02000000 | Response includes the SET-COOKIE header.
0x04000000 | Response includes the WWW-AUTHENTICATE header.
0x08000000 | Response includes the VIA header.
0x10000000 | Response includes the AGE header.
0x20000000 | Response includes the TRANSFER-ENCODING header.
0x40000000 | Response should not be cached.

Operating system values

Value | Description
0:3.95 | Windows 95 (16-bit)
2:4.10 | Windows 98 (32-bit)
2:4.0 | Windows 95 (32-bit)
3:4.0 | Windows NT 4.0
3:5.0 | Windows 2000


Packet Filter Log Fields

The following table lists packet filter log fields.

Field Position | Descriptive Name (Field Name) | Description
1 | Date (date) | Date the packet was received.
2 | Time (time) | The time the packet was received (service info fields).
3 | Source IP (r-ip) | The Internet protocol (IP) address of the source (remote) computer. The source computer is the computer from which the data packets originated.
4 | Destination IP (s-ip) | The IP address of the destination (local) computer. The destination computer is usually the ISA Server computer.
5 | Protocol (protocol) | The particular transport level protocol that is used during the connection, such as Transmission Control Protocol (TCP), User Datagram Protocol (UDP), or Internet Control Message Protocol (ICMP).
6 | Source port (or protocol type, if ICMP) (param#1) | For TCP and UDP protocols, the remote port used to create a connection. For ICMP protocol, the type used when creating the connection.
7 | Destination port (or protocol code, if ICMP) (param#2) | For TCP and UDP protocols, the local port used to create a connection. For ICMP protocol, the code used when creating the connection.
8 | TCP flags (tcp-flags) | For a TCP data packet, represents the TCP flag value in the IP header. The possible values are FIN, SYN, RST, PSH, ACK, and URG.
9 | Interface (s-filter-rule) | Indicates whether the packet was accepted (1) or dropped (0). By default, only dropped packets are logged.
10 | Interface IP address (s-interface) | Interface on which the packet was received; usually only one interface.
11 | Header (rs-ip-header) | The entire IP header of the data packet that generated the alert event. The IP header is logged in hexadecimal format.
12 | Payload (rs-payload) | A listing of a portion of the data packet (after the IP header) that generated the alert event. The IP packet is logged in hexadecimal format.


Administration Object Error Codes

The following are the COM object warning (WRN) and error (ERR) codes, defined in FpcErrorCodes.h.

Message ID | Code | Error in Hex | Description
S_FPCLOG_BAD_COLUMN_SELECTION | FPC_WRN(0x201) | 800400201 |
S_FPC_ALERTSRV_ALERT_NOT_FOUND | FPC_WRN(0x202) | 800400202 |
S_FPC_RESTORE_TEMP_CONFIG_LEFT | FPC_WRN(0x203) | 800400203 |
S_FPC_PUBLIC_KEYS_CHANGED_AFTER_RESTORE | FPC_WRN(0x204) | 800400204 | The array configuration was restored. However, configuration of the following array members is corrupted: %1. Reinstall ISA Server on those computers.
S_FPC_SERVICE_INACCESSIBLE | FPC_WRN(0x205) | 800400205 | The service is inaccessible.
S_FPC_SOME_SERVICES_FAILED_TO_RESTART_AFTER_RESTORE | FPC_WRN(0x206) | 800400206 | Not all services restarted successfully after restore.
E_FPC_CERTIFICATE_NOT_INSTALLED | FPC_ERR(0x300) | 800400300 | The certificate is not installed.
E_FPC_CROSS_PRIORITY_BOUNDARY | FPC_ERR(0x301) | 800400301 | You cannot change order across priority boundaries.
E_FPC_SELECTED_SERVER_UNAVAILABLE | FPC_ERR(0x302) | 800400302 |
E_FPC_BAD_ADMIN_ROOT | FPC_ERR(0x303) | 800400303 | The object cannot be used as a standalone object. You can only create instances of the Admin object.
E_FPC_DEST_NOT_IP | FPC_ERR(0x304) | 800400304 | This destination object is not defined using an IP address.
E_FPC_DEST_NOT_MASK | FPC_ERR(0x305) | 800400305 | This destination object is not defined using an IP-Mask pair.
E_FPC_NO_STORAGE | FPC_ERR(0x306) | 800400306 | The object does not have persistent storage.
E_FPC_OBJECT_INVALID | FPC_ERR(0x307) | 800400307 | The object is not valid.
E_FPC_STRING_BAD | FPC_ERR(0x308) | 800400308 | The string is empty or contains illegal characters such as a backslash.
E_FPC_EVENT_NOT_DEFINED | FPC_ERR(0x309) | 800400309 | The GUID of the alert cannot be found in the Events collection.
E_FPC_NON_REMOVAL_EVENT | FPC_ERR(0x30A) | 80040030A | ISA Server predefined events cannot be removed.
E_FPC_ALERT_KEY_INVALID | FPC_ERR(0x30B) | 80040030B | The additional key is out of range.
E_FPC_CANNOT_DEL_DEFAULT_RULE | FPC_ERR(0x30C) | 80040030C | The default rule cannot be removed.
E_FPC_CANNOT_MOVE_DEFAULT_RULE | FPC_ERR(0x30D) | 80040030D | The default rule's order of execution cannot be modified. It will always be last.
E_FPC_CANT_CHANGE_DEFAULT_RULE_DESCRIPTION | FPC_ERR(0x30E) | 80040030E | The default rule name cannot be changed.
E_FPC_CORRUPTED_OBJECT_DATA | FPC_ERR(0x30F) | 80040030F | The object's data is corrupted.
E_FPC_BAD_DESTINATION_SET_NAME | FPC_ERR(0x310) | 800400310 | The destination set specified does not exist.
E_FPC_BAD_SCHEDULE_TEMPLATE_NAME | FPC_ERR(0x311) | 800400311 | The schedule template specified does not exist.
E_FPC_INVALID_SERVER_NAME | FPC_ERR(0x312) | 800400312 |
E_FPC_STRING_CONTAINS_INVALID_CHARACTERS | FPC_ERR(0x313) | 800400313 | The server name contains invalid characters.
E_FPC_EMPTY_STRING | FPC_ERR(0x314) | 800400314 | The server name is empty or contains only spaces.
E_FPC_BAD_PROTOCOL_NAME | FPC_ERR(0x315) | 800400315 | The protocol specified does not exist.
E_FPC_VALUE_TOO_LARGE | FPC_ERR(0x316) | 800400316 | The value is larger than the maximum allowed.
E_FPC_VALUE_TOO_SMALL | FPC_ERR(0x317) | 800400317 | The value is smaller than the minimum allowed.
E_FPC_CREATE_CHILD_INSTANCE_FAILED | FPC_ERR(0x318) | 800400318 | Failed to create a child object.
E_FPC_COMPONENT_NOT_INSTALLED | FPC_ERR(0x319) | 800400319 | ISA Server component is not installed.
E_FPC_BAD_IP_FORMAT | FPC_ERR(0x31A) | 80040031A | You must provide a valid IP address.
E_FPC_IP_FROM_MORE_THAN_TO | FPC_ERR(0x31B) | 80040031B | The value of Ip_From must be lower than the value of Ip_To.
E_FPC_IP_PAIR_ALREADY_EXISTS | FPC_ERR(0x31C) | 80040031C | This IP range already exists in the list.
E_FPC_BAD_BANDWIDTH_CLASS_NAME | FPC_ERR(0x31D) | 80040031D | The bandwidth class specified does not exist.
E_FPC_ALERT_MUST_HAVE_ACTIONS | FPC_ERR(0x31E) | 80040031E | Alert object must have at least one action defined.
E_FPC_FAILED_TO_READ_DISK_SIZE_AND_TYPE | FPC_ERR(0x32F) | 80040032F |
E_FPC_REDIRECT_EMPTY | FPC_ERR(0x330) | 800400330 | The Redirection property cannot be empty.
E_FPC_EXTERNAL_REF_EXIST | FPC_ERR(0x331) | 800400331 |
E_FPC_BAD_DOMAIN | FPC_ERR(0x332) | 800400332 | The string is not a valid domain name.
E_FPC_ARRAY_NOT_EMPTY | FPC_ERR(0x333) | 800400333 |
E_FPC_MUST_USE_DS | FPC_ERR(0x334) | 800400334 | This functionality required Active Directory as ISA storage.
E_FPC_NAME_IN_PENDING_REMOVE | FPC_ERR(0x335) | 800400335 | The object is identical to an object that was removed but the object removal was not yet committed.
E_FPC_DEL_DEFAULT_POLICY | FPC_ERR(0x336) | 800400336 | The default policy cannot be removed.
E_FPC_DEL_USED_POLICY | FPC_ERR(0x337) | 800400337 | The policy is in use by some arrays and cannot be removed.
E_FPC_ARRAY_ALREADY_PROMOTED | FPC_ERR(0x338) | 800400338 |
E_FPC_CANT_MOVE_TO_STANDALONE_ARRAY | FPC_ERR(0x339) | 800400339 |
E_FPC_ALLREADY_HAVE_DS_CONNECTION | FPC_ERR(0x33A) | 80040033A |
E_FPC_REMOTE_SERVER_UNAVAILABLE | FPC_ERR(0x33B) | 80040033B |
E_FPC_DCOM_CONNECTION_FAILED | FPC_ERR(0x33C) | 80040033C |
E_FPC_SERVER_ALLREADY_CONNECTED | FPC_ERR(0x33D) | 80040033D |
E_FPC_NOT_IN_GLOBAL | FPC_ERR(0x33E) | 80040033E | The property is not available for enterprise settings.
E_FPC_EVENT_IN_USE | FPC_ERR(0x33F) | 80040033F | The event definition settings cannot be saved. Event(s) that are in use (have alerts defined) have been marked to be removed.
E_FPC_LAT_ENTRY_ALREADY_EXISTS | FPC_ERR(0x340) | 800400340 | The IP range already exists in the Local Address Table (LAT).
E_FPC_IP_NOT_INTERNAL | FPC_ERR(0x341) | 800400341 | The IP address specified is not internal.
E_FPC_IP_NOT_EXTERNAL | FPC_ERR(0x342) | 800400342 | The IP address specified is not external.
E_FPC_MISSING_PROPS | FPC_ERR(0x343) | 800400343 | Some required properties are not set.
E_FPC_PNAT_INTERNAL_SLOT_USED | FPC_ERR(0x344) | 800400344 | There is already a rule that defines a mapping for the internal port and IP specified.
E_FPC_PNAT_EXTERNAL_SLOT_USED | FPC_ERR(0x345) | 800400345 | There is already a rule that defines a mapping for the external port and IP specified.
E_FPC_PNAT_PROTOCOL_NOT_INBOUND | FPC_ERR(0x346) | 800400346 | The specified protocol is not a server protocol.
E_FPC_ARRAY_NO_POLICY | FPC_ERR(0x347) | 800400347 | There must be at least one active policy (either local or enterprise) for an array.
E_FPC_ALLOWRULE_WITH_ENTERPRISE | FPC_ERR(0x348) | 800400348 | Cannot set rule action to Allow when enterprise policy is active.
E_FPC_ADDRULE_NOLOCAL | FPC_ERR(0x349) | 800400349 | Cannot add rule: local policy is not allowed.
E_FPC_ALERTSRV_UNKNOWN_EVENT | FPC_ERR(0x34A) | 80040034A | The event signaled couldn't be found.
E_FPC_ALERTSRV_BAD_EVENT_GUID | FPC_ERR(0x34B) | 80040034B | The name must be a GUID. (for example: "{8FD90800-A628-11d2-9513-0008C7BCEFD3}")
E_FPC_ALERTSRV_DUPLICATED_ALERT | FPC_ERR(0x34C) | 80040034C | An alert with the same event GUID, server name and additional key is already defined.
E_FPC_ITEM_IN_USE | FPC_ERR(0x34D) | 80040034D |
E_FPC_ADDRULE_NOPUBLISHING | FPC_ERR(0x34E) | 80040034E | Cannot add rule: publishing is not allowed.
E_FPC_BAD_SITE | FPC_ERR(0x34F) | 80040034F |
E_FPC_ARRAY_POLICY_USE_DEFAULT | FPC_ERR(0x350) | 800400350 | Cannot modify array policy, it uses the default settings.
E_FPC_BACKUP_FILE_IS_NOT_ARRAY_CONFIGURATION | FPC_ERR(0x351) | 800400351 | Mismatch in backup file formats.
E_FPC_BACKUP_FILE_IS_NOT_ENTERPRISE_CONFIGURATION | FPC_ERR(0x352) | 800400352 | The given file does not contain enterprise policies configuration.
E_FPC_POLICY_ELEMENT_NOT_FOUND | FPC_ERR(0x353) | 800400353 |
E_FPC_LOW_RANGE_MORE_THAN_HIGH_RANGE | FPC_ERR(0x354) | 800400354 | The lower bound port must be smaller or equal than the upper bound.
E_FPC_PORT_OUT_OF_RANGE | FPC_ERR(0x355) | 800400355 | The port range should be between 1 and 65535.
E_FPC_BACKUP_FILE_SCHEMA_VERSION_ERROR | FPC_ERR(0x356) | 800400356 |
E_FPC_SCHEMA_NOT_INSTALLED | FPC_ERR(0x357) | 800400357 |
E_FPC_BAD_PLUGIN_PROTOCOL_NAME | FPC_ERR(0x358) | 800400358 |
E_FPC_BAD_CLIENT_SET_NAME | FPC_ERR(0x359) | 800400359 | The client set specified does not exist.
E_FPC_BAD_CONTENT_GROUP_NAME | FPC_ERR(0x35A) | 80040035A | The content group specified does not exist.
E_FPC_BAD_DIALUP_ENTRY_NAME | FPC_ERR(0x35B) | 80040035B | The dial-up entry specified does not exist.
E_FPC_BAD_REF_TYPE | FPC_ERR(0x35C) | 80040035C | This reference collection cannot include references of the requested type.
E_FPC_STORAGE_VER_MISMATCH | FPC_ERR(0x35D) | 80040035D |
E_FPC_SERVER_NOT_IN_LAT | FPC_ERR(0x35E) | 80040035E | The Local Address Table (LAT) must contain at least one IP address for each server in the array.
E_FPC_SCOPE_MUST_BE_ARRAY | FPC_ERR(0x35F) | 80040035F | The policy element scope must be array.
E_FPC_SCOPE_MUST_BE_ENTERPRISE | FPC_ERR(0x360) | 800400360 | The policy element scope must be enterprise.
E_FPC_NO_SPECIFIED_PROTOCOLS | FPC_ERR(0x361) | 800400361 | At least one protocol must be specified.
E_FPC_INVALID_MEM_USAGE_PERCENTAGE | FPC_ERR(0x362) | 800400362 | The cache memory usage percentage is invalid. Valid values are from 1 to 100.
E_FPC_NOT_COMMON_NETWORK_DIALUP_CONNECTION | FPC_ERR(0x363) | 800400363 | Not all the servers in the array have the specified network dial-up connection.
E_FPC_CANNOT_DEMOTE_ARRAY | FPC_ERR(0x364) | 800400364 | Restoring a .bif file (originated from DS) to a registry array is not supported.
E_FPC_NOT_FULL_URL | FPC_ERR(0x365) | 800400365 | The URL should start with http:
E_FPC_IP_SUBNET_MASK_CONFLICT | FPC_ERR(0x366) | 800400366 | No IP address can match the specified mask and subnet combination.
E_FPC_NO_CREDENTIALS | FPC_ERR(0x367) | 800400367 | You must specified Credentials.
E_FPC_DEL_ACTIVE_DIALUP | FPC_ERR(0x368) | 800400368 | Cannot delete the Active Dialup Entry.
E_FPC_NO_DIALUP_AVAILABLE | FPC_ERR(0x369) | 800400369 | Cannot use auto dial, there are no Dialup Entries.
E_FPC_SERVICE_IS_DOWN | FPC_ERR(0x36A) | 80040036A | The remote ISA Control Service is down or unaccessible on target server. Please ensure the service is running and accessible on this server in order to perform the operation.
E_FPC_CANNOT_PROMOTE_ARRAY | FPC_ERR(0x36B) | 80040036B | Restoring a bif file (originated from registry) to a DS array is not supported.
E_FPC_SERVER_LIST_MISMATCH_IN_BACKUP_FILE | FPC_ERR(0x36C) | 80040036C | Mismatch in server list between current array and restored array.
E_FPC_NOT_SUPPORTED_IN_STANDARD_EDITION | FPC_ERR(0x36D) | 80040036D | Method or property not available in Standard Edition.
E_FPC_DCOM_TO_DOMAINARRAY_UNSUPPORTED | FPC_ERR(0x36E) | 80040036E | Remote connection to DS based array is attempted (not supported).
E_FPC_BAD_LDT_DOMAIN_NAME_FORMAT | FPC_ERR(0x36F) | 80040036F | The string is not a valid LDT domain name.
E_FPC_MOVETO_AP_ONLY | FPC_ERR(0x370) | 800400370 | Cannot change enterprise policy settings to use array policy only.
E_FPC_MOVEFROM_AP_ONLY | FPC_ERR(0x371) | 800400371 | Cannot change policy settings to use an enterprise policy.
E_FPC_CHANGE_DEFAULT_AP_ONLY | FPC_ERR(0x372) | 800400372 | Cannot modify default enterprise policy settings. This is because one or more arrays in the enterprise use the default settings.
E_FPC_TCP_UDP_MISMATCH | FPC_ERR(0x373) | 800400373 | Invalid API was used for the specified protocol.
E_FPC_CACHE_REQUIRES_NTFS_DRIVE | FPC_ERR(0x374) | 800400374 | Cache can be configured on NTFS drives only.
E_FPC_SERVER_PUBLISHING_RULE_USE_INTERNAL | FPC_ERR(0x375) | 800400375 | The IP address %1 used as internal in server publishing rule %2.
E_FPC_SERVER_PUBLISHING_RULE_USE_EXTERNAL | FPC_ERR(0x376) | 800400376 | The IP address %1 used as external in server publishing rule %2.
E_FPC_MIN_MUST_BE_LESS_THAN_MAX | FPC_ERR(0x377) | 800400377 | Minimum should be less than maximum.
E_FPC_MISMATCH_POLICY | FPC_ERR(0x378) | 800400378 | Policy is different between backup file and current configuration.
E_FPC_MISMATCH_ALLOW_LOCAL_POLICY | FPC_ERR(0x379) | 800400379 | Allow is different between backup file and current configuration.
E_FPC_MISMATCH_ALLOW_PUBLISHING | FPC_ERR(0x37A) | 80040037A | Allow Publishing is different between backup file and current configuration.
E_FPC_MISMATCH_FORCE_PF | FPC_ERR(0x37B) | 80040037B | Force PF is different between backup file and current configuration.
E_FPC_NOT_CONTAINING_ARRAY | FPC_ERR(0x37C) | 80040037C | Notifications are allowed only on the containing array.
E_FPC_NEED_SERVER_FOR_CREDENTIALS | FPC_ERR(0x37D) | 80040037D | Cannot add credentials when there are no servers in the array.
E_FPC_INVALID_BACKUP_FILE | FPC_ERR(0x37E) | 80040037E | The selected file does not contain a complete backup image.
E_FPC_FILENAME_SHOULD_BE_LOCAL | FPC_ERR(0x37F) | 80040037F | The file must be located in the selected ISA server
E_FPC_INVALID_PORT | FPC_ERR(0x380) | 800400380 | You must provide a port number between 1 and 65535.
E_FPC_INVALID_PORT_INC_0 | FPC_ERR(0x381) | 800400381 | You must provide a port number between 0 and 65535.
E_FPC_UNABLE_TO_RETRIEVE_REGISTRY_SIZE | FPC_ERR(0x382) | 800400382 | Unable to retrieve registry size.
E_FPC_REGISTRY_TOO_SMALL_FOR_RESTORE | FPC_ERR(0x383) | 800400383 | The registry on the computer is not large enough to complete the restore operation.
E_FPC_MISMATCH_BETWEEN_CURRENT_AND_RESTORED_ARRAY | FPC_ERR(0x384) | 800400384 | The array configuration cannot be restored since there is a mismatch between the current array configuration and the restored array configuration.
E_FPC_IP_SHOULD_EXIST_ON_ISA_AND_EXTERNAL | FPC_ERR(0x385) | 800400385 | The specified IP address should be on at least one server in the array.
E_FPC_PUBLIC_KEYS_MISMATCH_IN_BACKUP_FILE | FPC_ERR(0x386) | 800400386 | If you use this backup file to restore the array configuration, configuration of the following array members will be corrupted, and you will have to reinstall ISA Server on these computers: %1.
E_FPC_ALL_PUBLIC_KEYS_MISMATCH_IN_BACKUP_FILE | FPC_ERR(0x387) | 800400387 | You cannot use this backup file to restore the array configuration.


Firewall Reference

The firewall reference provides information on the interfaces, enumerated types, and structures you will use in the development of application filters.

This section contains the following topics:

  • Filter Interfaces
  • Structures


Filter Interfaces

Filter interfaces expose the COM objects needed to develop application filters. Some of the interfaces are implemented by the Firewall service, some by the application filter. See the reference page for each interface for more information.

This section contains the following filter interfaces:

  • IFWXAcceptCompletion
  • IFWXConnection
  • IFWXDataFilter
  • IFWXExternalIOCompletion
  • IFWXFilter
  • IFWXFilterAdmin
  • IFWXFirewall
  • IFWXFirewallAction
  • IFWXGetXByY
  • IFWXImpersonator
  • IFWXIOBuffer
  • IFWXIOCompletion
  • IFWXIpFilter
  • IFWXNetworkSocket
  • IFWXOverlapped
  • IFWXSession
  • IFWXSessionFilter
  • IFWXSlowDataFilter
  • IFWXSocket
  • IFWXUdpDestination


IFWXAcceptCompletion

The IFWXAcceptCompletion interface receives notifications when an asynchronous accept operation on an IFWXNetworkSocket interface is completed by using the IFWXNetworkSocket::Accept method.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXAcceptCompletion Methods | Description
CompleteAsyncAccept | Receives notifications when the IFWXNetworkSocket::Accept method completes.

Implementation

This interface is implemented by the application filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXNetworkSocket::Accept


IFWXAcceptCompletion::CompleteAsyncAccept Method

This method is called when the IFWXNetworkSocket::Accept method completes (when a client connects to the socket).

HRESULT CompleteAsyncAccept(
  BOOL fSuccess,
  DWORD Win32ErrorCode,
  INetworkSocket *pListeningSocket,
  INetworkSocket *pAcceptSocket,
  LPSOCKADDR RemoteAddress,
  DWORD RemoteAddressLength,
  LPSOCKADDR LocalAddress,
  DWORD LocalAddressLength,
  UserContextType UserData
);

Parameters

fSuccess
[in] Success flag. If TRUE, the IFWXNetworkSocket::Accept method succeeded. If FALSE, it failed.
Win32ErrorCode
[in] Win32 error code. This parameter is defined only if the fSuccess parameter is FALSE.
pListeningSocket
[in] Pointer to the IFWXNetworkSocket interface on the listening socket.
pAcceptSocket
[in] Pointer to the IFWXNetworkSocket interface on the newly accepted connection.
RemoteAddress
[in] Pointer to a sockaddr structure that contains the remote address of the connection. This is the same information that would be returned by the Windows Sockets (Winsock) getpeername function.
RemoteAddressLength
[in] Size, in bytes, of the buffer pointed to by the RemoteAddress parameter.
LocalAddress
[in] Pointer to a sockaddr structure that contains the local address of the connection. This is the same information that would be returned by the Winsock getsockname function.
LocalAddressLength
[in] Size, in bytes, of the buffer to which the LocalAddress parameter points.
UserData
[in] The UserData parameter that was passed to the IFWXNetworkSocket::Accept method.

Return Values

S_OK
The method succeeded.

Any error should be handled with this method.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate among them by using different values for UserData.


IFWXConnection

The IFWXConnection interface implements functions specific to a particular connection.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXConnection Methods | Description
AttachDataFilter | Sets up a data filter for a connection.
AttachDataFilterWithDestination | Sets up a data filter that is valid only for a specific UDP destination.
EmulateConnection | Makes a connection to a client after emulating a bind method.
SetSocketName | Sets the socket name for an emulated bind.
Kill | Forces the connection to terminate.
GetExternalSocketName | Gets the socket name for the external side of the connection.
SetClientAddress | Gives the client address for a connection returned by the IFWXSession::BindForClient method, for which the client address was not previously specified.
SetProtocol | Associates the connection object with a specified protocol.
Deny | Denies the current operation.
SetBufferSize | Sets the buffer size for a connection.
GetExternalPeerName | Gets the peer name for the external side of the connection.
GetSession | Returns the session object to which a connection belongs.
SetIpFilter | Sets the IP filter for the connection.
GetIpFilter | Gets a copy of the IP filter object for the connection.

Implementation

This interface is implemented by the Firewall service.

Remarks

The connection object represented by the IFWXConnection interface implements functions specific to a particular connection. Every remote socket created on behalf of a client has a connection object associated with it.

A single TPC connection between a listening socket on the Firewall service and an external server may result in the creation of two connection objects: listening on the Firewall service, and inbound. When the remote server disconnects, the inbound connection is closed, but the listening connection may not close if FWX_FLAG_ALLOW_MULTIPLE was specified.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXConnection::AttachDataFilter Method

Attaches a data filter to this connection.

HRESULT AttachDataFilter(
  IFWXDataFilter *piDataFilter,
  DataFilterPriorityClass PriorityClass,
  IUnknown *punkFilterContext
);

Parameters

piDataFilter
[in] Pointer to the IFWXDataFilter interface of the Firewall service data filter object to use with this connection.
PriorityClass
[in] Priority class for the data filter. This determines the position of the data filter in relation to other data filters that may be attached to the connection. This parameter is a value from the FwxDataFilterPriorityClass enumeration.
punkFilterContext
[in] Pointer to the interface to use to pass contextual information to the data filter, such as the session to which the data filter is being attached. This interface is passed to the IFWXDataFilter::SetSockets method in the punkFilterContext parameter. This parameter can be NULL.

Remarks

This method can be called only in the context of the IFWXSessionFilter::FirewallEventHandler method while handling events with one of the following values:

fwx_AcceptedConnection

fwx_Bind_Udp

fwx_Connect_Tcp

fwx_Udp_Destination


IFWXConnection::AttachDataFilterWithDestination Method

Attaches a data filter to this connection. The data filter is associated with a remote destination.

HRESULT AttachDataFilterWithDestination(
  IFWXDataFilter *piDataFilter,
  DataFilterPriorityClass PriorityClass,
  IUnknown *punkFilterContext,
  LPSOCKADDR ExternalAddress,
  INT ExternalAddressLength
);

Parameters

piDataFilter
[in] Pointer to the IFWXDataFilter interface on the data filter to use with this connection.
PriorityClass
[in] Priority class for the data filter. This determines the position of the data filter in relation to other data filters that may be attached to the connection. This parameter is a value from the FwxDataFilterPriorityClass enumeration.
punkFilterContext
[in] Pointer to the interface to use to pass context information to the data filter. This interface is passed to the IFWXDataFilter::SetSockets method. This parameter can be NULL.
ExternalAddress
[in] Pointer to a sockaddr structure that contains the address of the peer of UDP datagrams for which the data filter is installed.

The data filter receives all datagrams sent through the connection but is removed if and when the service causes a destination to expire.

ExternalAddressLength
[in] Length, in bytes, of the ExternalAddress parameter.

Remarks

This method must be called only in the context of the IFWXSessionFilter::FirewallEventHandler method while handling an event of type fwx_Udp_Destination. This method would be used when you want the filter to attach only to data from a specific destination, even if the connection is not destination specific, as is the case for UDP connections.

The data filter will receive all of the packets on the connection.

The data filter will be detached from the connection automatically if the UDP destination expires.


IFWXConnection::Deny Method

Denies the current operation on the connection object.

HRESULT Deny(
  DWORD Reserved
);

Parameters

Reserved
[in] Reserved for future use. Must be zero.

Return Values

S_OK
The connection will be denied.
E_INVALIDARG
Invalid value was passed to the Reserved parameter.
FWX_E_BAD_CONTEXT
The method was not called while handling any of the supported events.

Remarks

This method is rarely used. Using "Protocol Rules" and "Site and Content Rules" administration methods is the preferred way to control user activity.

This method must only be called in the context of the IFWXSessionFilter::FirewallEventHandler method while handling events with one of the following values:

  • fwx_AcceptedConnection
  • fwx_Bind_Udp
  • fwx_Bind_Tcp
  • fwx_Connect_Tcp

The action that caused the event will be canceled. A bind operation will fail with error code 10048 (WSAEADDRINUSE), a connect operation will fail with error code 10061 (WSAECONNREFUSED). An accepted connection will be aborted.

Note For an fwx_Udp_Destination event, use the IFWXUdpDestination::Deny method instead of IFWXConnection::Deny. Outbound UDP packets sent to a denied destination will be discarded.


IFWXConnection::EmulateConnection Method

Creates a connection to a client for a filter-emulated listening connection.

HRESULT EmulateConnection(
  IFWXDataFilter *piDataFilter,
  LPSOCKADDR RemoteAddress,
  DWORD RemoteAddressLength,
  LPSOCKADDR LocalAddress,
  DWORD LocalAddressLength,
  IFWXConnection **ppNewIFWXConnection
);

Parameters

piDataFilter
[in] Pointer to the IFWXDataFilter interface on the data filter that supplies the data for the connection. The data filter is installed with fwx_dfpc_Emulation priority, which is closest to the Internet. The data filter only receives an interface of an internal socket. An external socket is assumed to be held by the caller.
RemoteAddress
[in] Pointer to a sockaddr structure that contains the address of the remote socket that is connecting to the client. This address is set in the output parameter of accept and getpeername functions on the client.
RemoteAddressLength
[in] Length, in bytes, of the RemoteAddress parameter.
LocalAddress
[in] Pointer to a sockaddr structure that contains the local proxy address that is used for the connection. This is the address that the getsockname function returns to the client.
LocalAddressLength
[in] Length, in bytes, of the LocalAddress parameter.
ppNewIFWXConnection
[out] Pointer to a variable that receives an IFWXConnection interface pointer on the connection object that is created for this new connection. The parameter can be NULL. The reference to the new connection object must not be held after a fwx_ConnectionTerminating event for that connection is received.

Remarks

This method may be called only if this connection is in the listening state, and the caller is a filter that is emulating the listening state for the connection. Clients use the emulated connection, so that, effectively, only one real connection is used.


IFWXConnection::GetExternalPeerName Method

Gets the peer name for the external socket. This method is implemented by calling the Winsock getpeername function on the actual external socket.

HRESULT GetExternalPeerName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to a sockaddr structure that receives the peer name.
AddressLength
[in, out] On input, this parameter specifies the size, in bytes, of the Address buffer. On output, it receives the size, in bytes, needed to hold the address.

Remarks

When the proxy is chained to another proxy, this function returns the value for the last proxy in the chain.

Note This method should not be called from the session event handling portion of your filter code; at that point in the code the network connection has not been established yet, and may be denied by the application filter or by another application filter. Typically you would call this method from within the IFWXDataFilter::SetSockets method of a data filter attached to the connection, that is, at a point when you are certain that the connection has been established.


IFWXConnection::GetExternalSocketName Method

Gets the socket name for the external socket. This method is implemented by calling the Winsock getsockname function on the actual external socket.

HRESULT GetExternalSocketName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to a sockaddr structure that receives the socket address (name).
AddressLength
[in, out] On input, this parameter specifies the size, in bytes, of the Address buffer. On output, it receives the size, in bytes, needed to hold the address.

Remarks

When the proxy is chained to another proxy, this function returns the value for the last proxy in the chain.

Note This method should not be called from the session event handling portion of your filter code; at that point in the code the network connection has not been established yet, and may be denied by the application filter or by another application filter. Typically you would call this method from within the IFWXDataFilter::SetSockets method of a data filter attached to the connection, that is, at a point when you are certain that the connection has been established.


IFWXConnection::GetIpFilter Method

Gets a copy of the IP filter object for the connection. Returns NULL if the connection is not limited to a range of IP addresses.

HRESULT GetIpFilter(
  IFWXIpFilter **ppIpFilter
);

Parameters

ppIpFilter
[out] Address of a variable that receives a pointer to the IFWXIpFilter interface.

Remarks

Because the returned object is a copy, modifying the object does not affect the connection.

See Also

IFWXIpFilter


IFWXConnection::GetSession Method

Returns the session object to which a connection belongs.

HRESULT GetSession(
  IFWXSession **ppSession
);

Parameters

ppSession
[out] Pointer to the session object.

Return Values

S_OK
The method succeeded.
FWX_E_TERMINATING
The socket is already closed.


IFWXConnection::Kill Method

Forces the connection to terminate.

HRESULT Kill()

Remarks

This method could be used to allow an administrator to end a group of connections.


IFWXConnection::SetBufferSize Method

Sets the buffer size for a connection.

HRESULT SetBufferSize(
  DWORD BufferSize
);

Parameters

BufferSize
[in] Buffer size to be used for this connection.

Return Values

S_OK
The method succeeded.
E_INVALIDARG
Invalid value was passed to the method.

Remarks

This method allows you to modify the buffer size for a connection. By default, the service uses buffers of 4096 bytes for UDP and 2048 for TCP. UDP datagrams larger than the default buffer size are dropped by the service. Use this function to set a larger buffer size for protocols that use packets larger than 4096 bytes.

For TCP, the buffer size is used for optimization. In general, it should not be modified. For UDP, datagrams larger than the buffer size can be dropped. If the filter determines that larger datagrams can be transmitted, it should set the buffer accordingly.


IFWXConnection::SetClientAddress Method

Gives the client address for a connection returned by the IFWXSession::BindForClient method for which the client address was not previously specified.

HRESULT SetClientAddress(
  LPSOCKADDR ClientAddress,
  DWORD ClientAddressLength
);

Parameters

ClientAddress
[in] Pointer to a sockaddr structure that contains the address that the client used.
ClientAddressLength
[in] Length, in bytes, of the ClientAddress parameter.

Return Values

S_OK
The method succeeded.
E_INVALIDARG
Invalid address passed to the method, or the client address was already specified.
HRESULT_FROM_WIN32(win32 error code)
Windows Sockets (Winsock) or Win32 error code. The method failed.


IFWXConnection::SetIpFilter Method

Sets the IP filter for the connection. Either sets a new IP filter if there had not been one or replaces the current IP filter with a new one.

HRESULT SetIpFilter(
  IFWXIpFilter *pIpFilter
);

Parameters

pIpFilter
[in] Pointer to the IFWXIpFilter interface. Setting this parameter equal to NULL will result in no IP address restrictions for this connection.

Remarks

This method should not be used for emulated connections.

See Also

IFWXIpFilter


IFWXConnection::SetProtocol Method

Attempts to associate the connection object with the specified protocol.

HRESULT SetProtocol(
  REFGUID ProtocolGuid,
  DWORD dwFlags
);

Parameters

ProtocolGuid
[in] GUID of the protocol to attempt to associate with the connection.
dwFlags
[in] This flag parameter can be a combination of the following values:
Value | Description
FWX_FLAG_EMULATE_PROTOCOL Indicates that the filter intends to emulate the connection if this call is successful.

For UDP and outbound TCP connections, a filter that specifies this flag must attach a data filter with fwx_dfpc_Emulation priority if the method call succeeds.

For inbound TCP connections, a filter must call the IFWXConnection::EmulateConnection method to attach a data filter.
FWX_FLAG_BIDIRECTIONAL | "Receive-Send" is allowed for UDP connections. Use this flag when SetProtocol is called for a fwx_Bind_Udp event.
0 | The filter will not emulate the connection.

Return Values

S_OK
The operation completed successfully.
FWX_E_PROTOCOL_RULES_DENIED
The protocol rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.
FWX_E_ALREADY_EMULATED
The connection is already emulated by another filter.

Remarks

This method must be called only in the context of the IFWXSessionFilter::FirewallEventHandler method while handling an event of type fwx_Connect_Tcp, fwx_Bind_Udp, or fwx_Bind_Tcp. The method checks the user permissions for the protocol and then attempts to associate the connection with the protocol based on those permissions.

For fwx_Udp_Destination events use the IFWXUdpDestination::SetProtocol method instead.


IFWXConnection::SetSocketName Method

Sets the name of the socket for the connection. Call this method only if the caller is emulating the connection.

HRESULT SetSocketName(
  LPSOCKADDR Address,
  DWORD AddressLength
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the socket address.
AddressLength
[in] Length, in bytes, of the Address parameter.

Return Values

S_OK
The method succeeded.
FWX_E_ALREADY_EXISTS
The socket is already bound.
FWX_E_INVALID_ARG
An invalid argument was provided to this method.

Remarks

On regular connections, the Firewall service calls the getsockname Winsock function on the external socket and passes this information to the Firewall client. For an emulated connection there is no external socket, or the external socket is known only to the filter. The filter is required to call this method and set the socket name.

When there is no connection, it is advisable to return an IP address of the Firewall service (external or internal as appropriate) because the client application may use this information to publish the address.


IFWXDataFilter

A filter must implement the IFWXDataFilter interface to hook into the data pump of the Firewall service.

Note When you use IFWXDataFilter, consider possible threading issues. For more information, see Best Practices.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXDataFilter Methods | Description
SetSockets | Gives the data filter the socket interfaces it should use.
Detach | Orders the data filter to release the references it holds to the sockets.

Implementation

This interface is implemented by the application filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXDataFilter::Detach Method

Detaches a data filter. When a data filter is detached it must release the references it holds to the socket interfaces and to the connection.

HRESULT Detach()

Return Values

S_OK
The method succeeded. S_OK must be returned by this method. Any error should be handled in this method.

Remarks

This method may be called before the SetSockets method to ensure cleanup in case of failures.


IFWXDataFilter::SetSockets Method

Sets the internal and external sockets for the data filter. When this function is called, the filter is expected to begin the data-pumping process between the sockets.

HRESULT SetSockets(
  IFWXSocket *piInternalSocket,
  IFWXSocket *pIExternalSocket,
  IFWXConnection *piConnection,
  IUnknown *punkFilterContext
);

Parameters

piInternalSocket
[in] Pointer to the IFWXSocket interface for an internal socket.
pIExternalSocket
[in] Pointer to the IFWXSocket interface for an external socket.
piConnection
[in] Pointer to the IFWXConnection interface on the connection object on which this data filter is installed.
punkFilterContext
[in] Pointer to the interface used to pass context information to the data filter. The parameter will have the same value as the punkFilterContext parameter of IFWXConnection::AttachDataFilter and IFWXSession::SetDataFilterFactory.

Return Values

S_OK
The method succeeded.
E_OUTOFMEMORY
Insufficient memory or resources to process the event. The connection will be terminated.

Remarks

A filter that is emulating a connection receives NULL for the external socket interface.


IFWXExternalIOCompletion

The IFWXExternalIOCompletion interface is the notification interface for Win32 input/output (I/O) operations for which the filter has a handle.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXExternalIOCompletion Methods | Description
CompleteAsyncIO | Receives notifications from the firewall service when a Win32 I/O operation completes.

Implementation

This interface is implemented by the application filter.

Remarks

This interface is similar in function to the IFWXIOCompletion interface but is used to call or write to Win32 files asynchronously.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXFirewall::HookToCompletionPort, IFWXFirewall::CreateOverlapped, IFWXOverlapped


IFWXExternalIOCompletion::CompleteAsyncIO Method

Called by the firewall service when a Win32 I/O operation completes.

HRESULT CompleteAsyncIO(
  BOOL fSuccess,
  DWORD NumberOfBytesTransfered,
  DWORD Win32ErrorCode,
  IFWXOverlapped *pOverlapped,
  UserContextType UserData
);

Parameters

fSuccess
[in] Success flag. If TRUE, the I/O operation succeeded. If FALSE, it failed.
NumberOfBytesTransfered
[in] Number of bytes transferred during a successful I/O operation.
Win32ErrorCode
[in] Win32 error code for a failed I/O operation.
pOverlapped
[in] Pointer to the IFWXOverlapped interface on the overlapped object used for this operation.
UserData
[in] The UserData parameter set in the call to the IFWXOverlapped::SetNotificationInterface method.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them by using different values for UserData.


IFWXFilter

The Firewall service uses the IFWXFilter interface to load and initialize a filter and to create session filters. An IFWXFilter interface is called for each filter that is in ISA storage and is enabled.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXFilter Methods | Description
FilterInit | Called by the Firewall service when the filter is starting.
FilterShutdown | Called by the Firewall service when the service is stopping.
AttachToSession | Called by the Firewall service when it determines that a session filter is needed.

Implementation

This interface is implemented by the application filter.

Remarks

This is the interface that is used to create the filter object; therefore, every filter must initially implement this interface. Only one instance of the IFWXFilter object is created per filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXFilter::AttachToSession Method

Creates a session filter object when the Firewall service detects an event for which the filter is registered. AttachToSession also indicates the set of events that the session filter will handle. This set of events includes the events requested in FilterInit. The events for which the filter is registered are received in a FWXFilterHookEvents structure.

The Firewall service object calls this interface when it detects an event for which the filter is registered.

HRESULT AttachToSession(
  IFWXSession *piSession,
  IFWXSessionFilter **piSessionFilter,
  PFilterHookEvents *ppFilterHookEvents
);

Parameters

piSession
[in] Pointer to the IFWXSession interface associated with the session to be monitored.
piSessionFilter
[out] Address of a variable that receives a pointer to the IFWXSessionFilter interface on the session filter object. The session filter object receives event notifications for the session.
ppFilterHookEvents
[out] Pointer to a PFilterHookEvents variable. This must be set to refer to a FwxFilterHookEvents structure containing the initial set of events that the filter monitors. Use the CoTaskMemAlloc function to allocate the structure. IFWXFirewall::DuplicateFilterHookEvents creates a duplicate of the FwxFilterHookEvents structure in a buffer that can be returned by IFWXFilter::AttachToSession.

Return Values

S_OK
The method succeeded.
E_OUTOFMEMORY
Insufficient memory or resources to process the event. This will cause the request that generated the event to fail.

See Also

IFWXFirewall::DuplicateFilterHookEvents


IFWXFilter::FilterInit Method

Initializes the filter and passes it an interface pointer to the Firewall service object. The Firewall service object provides general methods to the filter. For a list of the general methods see IFWXFirewall, the interface for the Firewall service object.

HRESULT FilterInit(
  IFWXFirewall *pIFWXFirewall,
  PFilterHookEvents *ppFilterHookEvents
);

Parameters

pIFWXFirewall
[in] Pointer to the IFWXFirewall interface on the firewall service. IFWXFirewall provides access to proxy services.
ppFilterHookEvents
[out] Pointer to a PFilterHookEvents variable. This must be set to refer to a FwxFilterHookEvents structure containing the initial set of events that the filter monitors. Use the CoTaskMemAlloc function to allocate the structure. IFWXFirewall::DuplicateFilterHookEvents creates a duplicate of the FwxFilterHookEvents structure in a buffer which can be returned by IFWXFilter::AttachToSession.

Return Values

S_OK
The connection will be denied.
FAILED
The connection is aborted.

Remarks

Place in FilterInit all initializations, particularly events to monitor, as well as the reading of configurations and the creation of listening sockets.

See Also

IFWXFirewall::DuplicateFilterHookEvents


IFWXFilter::FilterShutdown Method

Begins the shutdown sequence for the filter object when the Firewall service is shutting down.

HRESULT FilterShutdown()

Return Values

S_OK
The method succeeded.

Any error should be handled in this method.

Remarks

When shutting down the filter, the Firewall service releases references to all filter-implemented objects, after first making calls to the Detach method where applicable (either IFWXSessionFilter::Detach or IFWXDataFilter::Detach). However, because of the asynchronous nature of the proxy, the order of calling Detach/IFWXFilter::FilterShutdown is undefined, and the Firewall service may call the Detach method after IFWXFilter::FilterShutdown is returned. When the Firewall service calls Detach after IFWXFilter::FilterShutdown has been returned, filter-implemented objects may still be in the process of shutting down. Typically, the shutdown of filter-implemented objects does not have to be considered in filter design because the shutdown of objects occurs in the context of proxy worker threads. When the service stops, the Firewall service waits until all its worker threads have terminated and the shutdown operations have completed.

However, if the filter is doing shutdown work in a context other than a proxy worker thread — for example, a remote procedure call (RPC) worker thread or a timer callback thread — the nonproxy thread may execute code after all proxy worker threads have ended. Thus, the nonproxy thread will not have an appropriate context in which to execute the code. To avoid this situation, FilterShutdown must not be returned until all shutdown work has completed in the nonproxy worker thread contexts.


IFWXFilterAdmin

The IFWXFilterAdmin interface is used by filter setup to install and configure the filter.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXFilterAdmin Methods | Description
InstallFilter | Installs a filter.
UninstallFilter | Uninstalls a filter.
RegisterProtocolForFilter | Registers a protocol that is controlled by a filter.
UnregisterProtocolForFilter | Unregisters a protocol that is controlled by a filter.
GetProtocol | Gets a previously defined protocol.
GetParameterSets | Gets an interface that provides access to the filter's set of parameters.
GetFilterParameterSet | Gets an interface that provides access to the filter's private configuration parameter set.
GetFilter | Gets the IFPCApplicationFilter interface, which provides access to information about the application filter configuration.
GetConfigurationType | Gets ISA Server configuration information.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXFilterAdmin::GetConfigurationType Method

Gets ISA Server configuration information.

HRESULT GetConfigurationType(
  BOOL *pIsADSConfiguration,
  BOOL *pIsArrayPolicyAllowed,
  BOOL *pIsEnterprisePolicyUsed
);

Parameters

pIsADSConfiguration
[out] Boolean that indicates whether the ISA Server is configured to use the Active Directory service.
pIsArrayPolicyAllowed
[out] Boolean that indicates whether the ISA Server is configured to allow array policy.
pIsEnterprisePolicyUsed
[out] Boolean that indicates whether the ISA Server is configured to use enterprise policy.

Remarks

For a stand-alone server or in the ISA Server Standard Edition, these parameters are as follows:

pIsDSConfiguration = FALSE;

pEnterprisePolicyUsed = FALSE;

pAllowArray = TRUE


IFWXFilterAdmin::GetFilterParameterSet Method

Gets an interface that provides access to the filter's private configuration parameter set.

HRESULT GetFilterParameterSet(
  REFCLSID guidFilter,
  FwxScope Scope,
  IFPCVendorParametersSet **ppParameterSet
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object for which the parameter set is required.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. The value fwx_DefaultScope can be used by Get operations to retrieve the object scope that is appropriate for the current configuration. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.
ppParameterSet
[out] Address of a variable that receives the interface pointer to the parameter set.

Remarks

This method gets a parameters set (from the parameters sets collection) with the same GUID as the filter GUID.

See Also

FPCVendorParametersSet


IFWXFilterAdmin::GetParameterSets Method

Gets an interface that provides access to the collection of parameter sets.

HRESULT GetParameterSets(
  REFCLSID guidFilter,
  FwxScope Scope,
  IFPCVendorParametersSets **ppParametersSets
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object for which the parameter sets collection is required.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. The value fwx_DefaultScope can be used by get operations to retrieve the object scope that is appropriate for the current configuration. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.
ppParametersSets
[out] Address of a variable that receives the interface pointer to the collection of parameters sets.

Remarks

Use this method to get the collection of parameters sets.

See Also

FPCVendorParametersSets


IFWXFilterAdmin::GetFilter Method

Gets the IFPCApplicationFilter interface, which provides access to information about the application filter configuration.

HRESULT GetFilter(
  REFCLSID guidFilter,
  FwxScope Scope,
  IFPCApplicationFilter **ppFilter
);

Parameters

guidFilter
[in] Class identifier (CLSID) of an FPCApplicationFilter object.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. The value fwx_DefaultScope can be used by get operations to retrieve the object scope that is appropriate for the current configuration. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.
ppFilter
[out] Address of a variable that receives the interface pointer to the FPCApplicationFilter object.

Return Values

S_OK
Method succeeded.
E_OUTOFMEMORY
Insufficient memory or resources; method failed.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
A filter with that GUID does not exist.


IFWXFilterAdmin::GetProtocol Method

Gets the FPCFilterProtocol interface, which provides access to a protocol previously installed by IFWXFilterAdmin::RegisterProtocolForFilter.

HRESULT GetProtocol(
  REFCLSID guidFilter,
  REFGUID guidProtocol,
  FwxScope Scope,
  IFPCFilterProtocol **ppProtocol
);

Parameters

guidFilter
[in] CLSID of an IFWXFilter object.
guidProtocol
[in] GUID that will be used for uniquely identifying the protocol.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. The value fwx_DefaultScope can be used by get operations to retrieve the object scope that is appropriate for the current configuration. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.
ppProtocol
[out] Address of a variable that receives the interface pointer to the FPCFilterProtocol object.

Return Values

S_OK
Method succeeded.
E_OUTOFMEMORY
Insufficient memory or resources; method failed.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
A filter with that GUID does not exist.

Remarks

Use this method to change the conifguration of a protocol.


IFWXFilterAdmin::InstallFilter Method

Registers the filter with ISA Server.

HRESULT InstallFilter(
  REFCLSID guidFilter,
  LPCSTR Name,
  LPCSTR Description,
  LPCSTR Vendor,
  LPCSTR VersionString,
  LPCSTR Reserved,
  FwxScope Scope
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object to install.
Name
[in] Pointer to the short name of the filter.
Description
[in] Pointer to the description of the filter.
Vendor
[in] Pointer to the name of the company that wrote the filter.
VersionString
[in] Pointer to a string representation for the version of the filter.
Reserved
[in] Reserved for future use. Passes a null pointer.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.

Return Values

S_OK
The filter was installed successfully.
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)
The filter is already installed.

Remarks

The Firewall service uses the CLSID of the filter when loading it. The name, description, vendor, and version string are used for displaying information about the filter in ISA Management, and are not parsed or interpreted by the proxy.

On an array, InstallFilter should be called for each array member. ISA keeps track of application filter installation for each server and will alert users if a filter is installed on some, but not all array members.


IFWXFilterAdmin::RegisterProtocolForFilter Method

Registers a protocol controlled by a given filter. A registered protocol will appear in ISA Management.

HRESULT RegisterProtocolForFilter(
  REFCLSID guidFilter,
  REFGUID guidProtocol,
  LPCSTR szProtocolName,
  LPCSTR szDescription,
  LPCSTR Reserved,
  FwxScope Scope
);

Parameters

guidFilter
[in] CLSID of an IFWXFilter object. Each registered protocol is associated with an IFWXFilter object and is valid only when that filter is installed.
guidProtocol
[in] GUID that will be used for uniquely identifying the protocol.
szProtocolName
[in] Pointer to the name of the protocol as it is to appear in ISA Management.
szDescription
[in] Pointer to the description text for the protocol.
Reserved
Reserved for future use. Passes a null string.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.

Return Values

S_OK
The protocol was installed, and the filter for guidFilter is properly installed.
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)
The protocol is already defined.
Error code
The protocol registration failed.

Remarks

Protocols can be recognized directly by the Firewall service, or the filter can control the service's recognition of the protocol. The advantage of filter control of protocol recognition is that a filter can recognize which protocol is associated with a secondary connection, whereas the Firewall service cannot do so independently.

See Also

IFWXConnection::SetProtocol, IFWXSession::AccessCheck


IFWXFilterAdmin::UninstallFilter Method

Removes the filter registration from the ISA configuration.

HRESULT UninstallFilter(
  REFCLSID guidFilter,
  FwxScope Scope
);

Parameters

guidFilter
[in] CLSID of the IFWXFilter object to uninstall.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.

Remarks

Use this method in an uninstall procedure.

On an array, ISA keeps a list of the servers for which InstallFilter was called. UninstallFilter removes the current server from that list. The filter object will be removed only when when the call to UninstallFilter causes the list to be empty.


IFWXFilterAdmin::UnregisterProtocolForFilter Method

Unregisters a protocol controlled by a given filter.

HRESULT UnregisterProtocolForFilter(
  REFCLSID guidFilter,
  REFGUID guidProtocol,
  FwxScope Scope
);

Parameters

guidFilter
[in] CLSID of an IFWXFilter object. Each registered protocol is associated with an IFWXFilter object and is valid only when that filter is installed.
guidProtocol
[in] GUID of the protocol to be removed.
Scope
[in] The scope of the filter object, either array or enterprise, as a value from the FwxScope enumerated type. This parameter cannot be set to fwx_EnterpriseScope for a stand-alone server or for ISA Server Standard Edition.

Return Values

S_OK
The protocol was removed successfully.
Error code
The protocol was not removed.

Remarks

Use this method in an uninstall procedure.


IFWXFirewall

The IFWXFirewall interface provides access to Firewall service functions for application filters that are not tied to any specific user session.

The Firewall service implements this interface and passes it to the IFWXFilter::FilterInit method.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXFirewall Methods | Description
HookToCompletionPort | Associates a handle with the Firewall service completion port.
CreateOverlapped | Creates an overlapped object for use with handles associated with the completion port.
CreatePrivateSession | Creates a private session object for a given client.
CreateNetworkSocket | Creates a socket object that works through the dynamic packet filter.
CreateConstBuffer | Creates a buffer object that wraps a user-supplied memory buffer.
CreateBuffer | Creates (allocates) a buffer object of the given size.
CreateWindowBuffer | Creates a buffer object that represents a window inside another buffer.
CreateIpFilter | Creates an IP filter object.
StartHeavyBlockingOperation | Notifies the Firewall service that a thread is busy with a lengthy blocking operation.
EndHeavyBlockingOperation | Notifies the Firewall service that a lengthy blocking operation has ended.
IsInternal | Checks if an address is internal (in the Local Address Table (LAT)).
GetNATSession | Gets a SecureNAT session object for a given client address.
DuplicateFilterHookEvents | Creates a duplicate of a given FwxFilterHookEvents structure.
GetHostByName | Retrieves host information corresponding to a host name.
GetHostByAddr | Retrieves host information corresponding to an address.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXFilter::FilterInit


IFWXFirewall::CreateBuffer Method

Allocates a buffer object of the given size.

HRESULT CreateBuffer(
  DWORD dwBufferLength,
  IFWXIOBuffer **pIOBuffer
);

Parameters

dwBufferLength
[in] Number of bytes to allocate.
pIOBuffer
[out] Address of a variable that receives a pointer to the IFWXIOBuffer interface.

Remarks

Use to create an empty buffer for data that is not constant. To create a buffer for data that is constant, use the IFWXFirewall::CreateConstBuffer method.

Filters are not required to use this method. A filter may provide its own buffer objects as long as they support the IFWXIOBuffer interface.

See Also

IFWXFirewall::CreateConstBuffer, IFWXFirewall::CreateWindowBuffer.


IFWXFirewall::CreateConstBuffer Method

Creates a buffer object that wraps the given data.

HRESULT CreateConstBuffer(
  BYTE *pBuffer,
  DWORD dwBufferLength,
  IFWXIOBuffer **pIOBuffer
);

Parameters

pBuffer
[in] Pointer to the data buffer.
dwBufferLength
[in] Length, in bytes, of the buffer pointed to by pBuffer.
pIOBuffer
[out] Address of a variable that receives a pointer to the IFWXIOBuffer interface.

Remarks

Use only when the data is known to be a constant and the buffer memory does not have to be freed. To create a buffer for data that is not constant, use the IFWXFirewall::CreateBuffer method.


IFWXFirewall::CreateIpFilter Method

Creates an IP filter object that implements the IFWXIpFilter interface.

HRESULT CreateIpFilter(
  IFWXIpFilter **ppIpFilter
);

Parameters

ppIpFilter
[out] Address of a variable that receives a pointer to the IFWXIpFilter interface.


IFWXFirewall::CreateNetworkSocket Method

Creates a TCP/IP socket.

HRESULT CreateNetworkSocket(
  INT Protocol,
  IFWXNetworkSocket **piSocket
);

Parameters

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The method will create a TCP socket.
FWX_PROTOCOL_UDP | The method will create a UDP socket.

piSocket
[out] Address of a variable that receives a pointer to the IFWXNetworkSocket interface.

Remarks

Filters must use this interface and not call the Winsock dynamic-link library (DLL) directly to create a socket. The ISA socket object automatically opens packet filter ports required for any operation made with this socket. Sockets created with the Winsock DLL will not work with ISA's packet filtering.

A socket created by this method is not associated with a specific user and will therefore always be successfully created regardless of ISA access policy. To create a socket that is user specific, use the IFWXSession::CreateNetworkSocket method.


IFWXFirewall::CreateOverlapped Method

Creates an overlapped object that supports the IFWXOverlapped interface for use with handles hooked to the completion port with the HookToCompletionPort method.

HRESULT CreateOverlapped(
  IFWXOverlapped **ppOverlapped
);

Parameters

ppOverlapped
[out] Address of a parameter that receives a pointer to the IFWXOverlapped interface.

See Also

IFWXExternalIOCompletion


IFWXFirewall::CreatePrivateSession Method

Creates a private session object for a given client.

HRESULT CreatePrivateSession(
  LPSOCKADDR ClientAddress,
  DWORD ClientAddressLength,
  LPSOCKADDR ProxyInternalAddress,
  DWORD ProxyInternalAddressLength,
  IFWXImpersonator *Impersonator,
  IFWXSession **ppPrivateSession
);

Parameters

ClientAddress
[in] Pointer to a sockaddr structure that contains the address of the client for which the session object is needed.
ClientAddressLength
[in] Length, in bytes, of the structure pointed to by the ClientAddress parameter.
ProxyInternalAddress
[in] Pointer to a sockaddr structure that contains the internal address of the proxy used to communicate with the client.
ProxyInternalAddressLength
[in] Length, in bytes, of the structure pointed to by the ProxyInternalAddress parameter. On a multihomed computer, one with more than one internal interface, the filter uses this parameter to set which interface is to be used. Can be NULL, in which case the Firewall service will select the internal interface.
Impersonator
[in] Pointer to impersonator object that will be used for impersonating the session's user. This parameter can be NULL, in which case only the client IP address will be used when processing rules.
ppPrivateSession
[out] Address of a parameter that receives a pointer to the IFWXSession interface on the newly created session.

Remarks

A private session object allows a filter to use an application-level authentication scheme.

Private sessions may be needed in outbound and inbound scenarios.

Outbound scenario: Session objects are created automatically for Firewall service or SecureNAT client requests, but not when an application connects to an internal address of the ISA Server through an application filter. A filter that acts as an application-level proxy, may have to create a private session object by using the CreatePrivateSession method to have access to session-dependent functions.

Inbound Scenario: Inbound primary connections can be directed to a SecureNAT client by using the CreatePrivateSession or IFWXFirewall::GetNATSession method. Use IFWXFirewall::CreatePrivateSession when the inbound connection has been requested by an application, the SecureNAT client is not known by the Firewall service, and no session object has been created. Use IFWXFirewall::GetNATSession only if the filter can assert that the client is configured to be a SecureNAT client of that server.


IFWXFirewall::CreateWindowBuffer Method

Creates a buffer object that represents a window inside another buffer.

HRESULT CreateWindowBuffer(
  IFWXIOBuffer *pIOBufferOriginal,
  DWORD dwOffset,
  DWORD dwLength,
  IFWXIOBuffer **pIOBuffer
);

Parameters

pIOBufferOriginal
[in] Pointer to the IFWXIOBuffer interface on the buffer object from which the window should be taken.
dwOffset
[in] Offset in the original buffer of the beginning of the window.
dwLength
[in] Length, in bytes, of the window.
pIOBuffer
[out] Address of a variable that receives a pointer to the IFWXIOBuffer interface.

Remarks

This method allows you to point to a portion of a buffer, so that a portion of it can be sent.


IFWXFirewall::DuplicateFilterHookEvents Method

Creates a duplicate of the given FwxFilterHookEvents structure in a buffer allocated by using the COM function CoTaskMemAlloc. This buffer can be returned by the IFWXFilter::FilterInit and IFWXFilter::AttachToSession methods.

HRESULT DuplicateFilterHookEvents(
  FilterHookEvents *pEventsToDuplicate,
  FilterHookEvents **ppCopy
);

Parameters

pEventsToDuplicate
[in] Pointer to the FilterHookEvents structure to copy.
ppCopy
[out] Pointer to a buffer that receives the new FilterHookEvents structure.


IFWXFirewall::EndHeavyBlockingOperation Method

Marks the end of a blocking operation. For more information, see StartHeavyBlockingOperation.

HRESULT EndHeavyBlockingOperation()

Return Values

S_OK
Method succeeded.
FWX_E_NOT_IN_BLOCKING_OP
There is no blocking operation to end.


IFWXFirewall::GetHostByAddr Method

Retrieves host information corresponding to an address.

HRESULT GetHostByAddr(
  const char *addr,
  int len,
  int type,
  char *buf,
  int *buflen
);

Parameters

addr
[in] Pointer to the network address for the host. Host addresses are stored in network byte order.
len
[in] Length of the address.
type
[in] Type of the address.
buf
[out] Pointer to the data area to receive the hostent data. The data area must be larger than the size of a hostent structure because the supplied data area is used by Windows Sockets to contain a hostent structure and all of the data referenced by members of the hostent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
buflen
[in, out] On input, specifies the size of data area for the buf parameter. If the buffer is too small, the error code ERROR_INSUFFICIENT_BUFFER is returned and the buflen parameter receives the size of the required buffer.

Return Values

S_OK
Success, the buffer was filled with the host information.
HRESULT_FROM_WIN32(WSAENOBUFS)
An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full.
HRESULT_FROM_WIN32(WSAHOST_NOT_FOUND)
Authoritative answer host not found.
HRESULT_FROM_WIN32(WSATRY_AGAIN)
A nonauthoritative host not found, or SERVERFAIL.
HRESULT_FROM_WIN32(WSANO_DATA)
Valid name, no data record of requested type.
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)
The buffer is too small. See the description of the buflen parameter.

Remarks

Unlike the IFWXSession::GetHostByAddr method, this method does not check permissions or site and content rules, does not log the name resolution, and cannot use autodial to dial out for the name resolution.


IFWXFirewall::GetHostByName Method

Retrieves host information corresponding to a host name. This method is similar to the WinSock gethostbyname method.

HRESULT GetHostByName(
  const char *name,
  char *buf,
  int *buflen
);

Parameters

name
[in] Pointer to the null-terminated name of the host.
buf
[out] Pointer to the data area to receive the hostent data. The data area must be larger than the size of a hostent structure because the supplied data area is used by Windows Sockets to contain a hostent structure and all of the data referenced by members of the hostent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
buflen
[in, out] On input, specifies the size of data area for the buf parameter. If the buffer is too small, the error code ERROR_INSUFFICIENT_BUFFER is returned and the buflen parameter receives the size of the required buffer.

Return Values

S_OK
Success, the buffer was filled with the host information.
HRESULT_FROM_WIN32(WSAENOBUFS)
Insufficient buffer space is available. (The buffer pointed to by buf is not large enough to contain the host information.)
HRESULT_FROM_WIN32(WSAHOST_NOT_FOUND)
Authoritative answer host not found.
HRESULT_FROM_WIN32(WSATRY_AGAIN)
A nonauthoritative host not found, or SERVERFAIL.
HRESULT_FROM_WIN32(WSANO_DATA)
Valid name, no data record of requested type.

Remarks

Unlike the IFWXSession::GetHostByName method, this method does not check permissions or site and content rules, does not log the name resolution, and cannot use autodial to dial out for the name resolution.


IFWXFirewall::GetNATSession Method

Gets, or if necessary, creates a SecureNAT session object for a given client.

HRESULT GetNATSession(
  LPSOCKADDR Address,
  DWORD AddressLength,
  IFWXSession **ppiPNATSession
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address of the SecureNAT client for which the session object is needed. The port is ignored.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
ppiPNATSession
[out] Address of a variable that receives a pointer to the IFWXSession interface on the SecureNAT session object for the given address.

Remarks

Inbound primary connections can be directed to a SecureNAT client by using the IFWXFirewall::CreatePrivateSession or IFWXFirewall::GetNATSession method. Use IFWXFirewall::CreatePrivateSession when the inbound connection has been requested by an application, the SecureNAT client is not known by the Firewall service, and no session object has been created. Use IFWXFirewall::GetNATSession only if the filter can assert that the client is configured to be a SecureNAT client of that server.


IFWXFirewall::HookToCompletionPort Method

Associates a handle with the Firewall service completion port. The caller must use overlapped structures that are provided by the Firewall service by using the IFWXOverlapped interface. Overlapped objects are obtained by calling the CreateOverlapped method.

HRESULT HookToCompletionPort(
  DWORD h
);

Parameters

h
[in] Win32 handle that should be associated with the Firewall service completion port.

See Also

IFWXExternalIOCompletion


IFWXFirewall::IsInternal Method

Checks whether the given address is in the Local Address Table (LAT).

HRESULT IsInternal(
  LPSOCKADDR Address,
  INT AddressLength
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to be checked.
AddressLength
[in] Length, in bytes, of the address specified in the Address parameter.

Return Values

S_OK
The address is in the LAT (internal).
S_FALSE
The address is not in the LAT (external).
FWX_E_INVALIDARG
The address is invalid or not an IP address.


IFWXFirewall::StartHeavyBlockingOperation Method

Notifies the Firewall service that a thread is busy with a lengthy blocking operation.

HRESULT StartHeavyBlockingOperation()

Return Values

S_OK
Method succeeded.
FWX_E_ALREADY_IN_BLOCKING_OP
The blocking operation is already started.

Remarks

The StartHeavyBlockingOperation and EndHeavyBlockingOperation methods manage the creation of additional completion-port worker threads when all existing threads are blocked. The completion port model works best when all I/O operations are overlapped. When some calls are blocking, all worker threads may be blocked, and the service will be idle. When this method is used the Firewall service keeps track of the number of threads that are busy with blocking operations and creates new threads when necessary.

Call the StartHeavyBlockingOperation method before making a blocking operation such as a call to the gethostbyname function or reading (non-overlapped) from a file or a pipe. Call EndHeavyBlockingOperation after the blocking call returns.

Do not call StartHeavyBlockingOperation before waiting for a critical section or a resource on which other threads are likely to be blocked. If the newly created thread is blocked on the same critical section, there will be greater congestion on the critical section and more context switches, resulting in an overall reduction in performance.


IFWXFirewallAction

The IFWXFirewallAction interface cancels a firewall action.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXFirewallAction Methods | Description
Cancel | Cancels the action.

Implementation

This interface is implemented by the Firewall service.

Remarks

A filter may request that the Firewall service perform a firewall action, such as connecting to a certain target, based on a firewall event or address. A firewall action is always requested in anticipation of an event that may not occur. This interface permits cancellation of the Firewall service action request. Typically, a firewall action relates only to events for which a filter is not registered.

For example, if the action is the future establishment of a secondary connection, IFWXFirewallAction can be used to cancel the action if the primary connection is terminated.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXFirewallAction::Cancel Method

Cancels a Firewall service action.

HRESULT Cancel();

Return Values

S_OK
The method succeeded.
FWX_E_TERMINATING
The action has already been canceled.

Remarks

The Firewall service can automatically cancel certain actions, including:

  • Actions that are supposed to happen only once (the action is canceled after its first occurrence).
  • Actions that have a timeout.
  • An action associated with a session that has been killed.

See Also

IFWXSession::AllowFutureConnect, IFWXSession::SetDataFilterFactory


IFWXGetXByY

This interface allows a filter to modify the result of remote gethostbyname or gethostbyaddr calls made by a Firewall client.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXGetXByY Methods | Description
Deny | Denies the name-resolution request.
SetResult | Sets the hostent structure that will be returned.

Implementation

This interface is implemented by the Firewall service.

Remarks

The IFWXGetXByY interface essentially overrides the gethostbyname or gethostbyaddr functions, returning a hostent structure with different contents than would have been returned by the unfiltered calls. The filter has to call this interface from within IFWXSessionFilter::FirewallEventHandler.

A typical use of this interface would be to return an IP address other than that requested by the client; that is, to redirect the request.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXGetXByY::Deny Method

Denies the name-resolution request.

HRESULT Deny(
  DWORD Reserved
);

Parameters

Reserved
Reserved for future use. Must be zero.

Return Values

S_OK
The Deny method succeeded.
FWX_E_TERMINATING
The IFWXGetXByY object is no longer valid.

Remarks

FWX_E_TERMINATING would be returned if the filter called this interface from any point other than within the IFWXSessionFilter::FirewallEventHandler function because IWspGetXByY can no longer affect the results.

See Also

FwxGetHostByAddrEvent, FwxGetHostByNameEvent


IFWXGetXByY::SetResult Method

Overrides the name resolution result with the specified hostent structure.

HRESULT SetResult(
  LPHOSTENT Hostent
);

Parameters

Hostent
[in] Pointer to a buffer containing a hostent structure that will be returned to the client.

Return Values

S_OK
The method succeeded.
FWX_E_TERMINATING
The object is no longer valid.

See Also

FwxGetHostByAddrEvent, FwxGetHostByNameEvent


IFWXImpersonator

The impersonator object holds user information so that the Firewall service can impersonate the user.

Impersonators must be implemented as in-process servers.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IImpersonator Methods | Description
Impersonate | Impersonates the user's account.
RevertToSelf | Undoes impersonation.

Implementation

This interface is implemented by the application filter.

Remarks

Impersonators are typically implemented by the Firewall service, as in the case when the service is performing an access check. This holds true for sessions that were created by the Firewall service. When a session has been created by a filter by using the IFWXFirewall::CreatePrivateSession method, impersonation is performed by the application filter on behalf of the Firewall service through IFWXImpersonator.

Impersonators can also be implemented by filters that hold user credentials and are designed to function as application gateways. A filter implements IFWXImpersonator by using IFWXSession::ImpersonateClient and IFWXSession::RevertToSelf.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXFirewall::CreatePrivateSession


IFWXImpersonator::Impersonate Method

Impersonates an authenticated user.

HRESULT Impersonate()

Return Values

S_OK
Impersonation succeeded.
FWX_E_NOT_AUTHENTICATED
Cannot impersonate the user because the session is not authenticated.

See Also

IFWXSession::ImpersonateClient


IFWXImpersonator::RevertToSelf Method

Causes the Firewall service to revert to its own access level after a successful call to the Impersonate method.

HRESULT RevertToSelf()

See Also

IFWXSession::RevertToSelf


IFWXIOBuffer

The buffer object points to a reference-counted memory buffer and provides means of managing the buffer.

The following rules apply to these buffers:

  • The allocator of a buffer owns the buffer. Only the allocator may alter the contents of the buffer. This means that the receiver must not modify a buffer received in the IFWXIOCompletion::CompleteAsyncIO method after a call to the IFWXSocket::Recv method with the IOBuffer parameter set to NULL.
  • A buffer that is sent (by way of the IFWXSocket::Send or IFWXSocket::SendTo method) must remain valid and unmodified until the reference count reaches zero. Even the owner of the buffer is not allowed to modify a buffer after it is sent.

The Send, SendTo, and Recv methods increment the reference count on the buffer. This reference is kept until CompleteAsyncIO returns. You must call Release for each AddRef that you called, and once more if you also created the buffer. Call AddRef if you keep a pointer to the buffer.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXIOBuffer Methods | Description
GetBufferAndSize | Gets the actual buffer and its size.
SetDataSize | Sets the actual size of the buffer that was used.
Append | Appends a specified number of bytes of data to the buffer object.
ReadAt | Reads a specified number of bytes starting at a specified offset from the beginning of the buffer.
SendToBuffer | Appends data from this buffer to another buffer.
GetBufferSizes | Gets the allocated and actual buffer sizes.

Remarks

This interface is generally implemented by the Firewall service. You may want to implement IFWXIOBuffer in your filter if:

  • You already have an allocated buffer that you want to send, and want to avoid creating a buffer copy. For example, the buffer was received from an RPC call or an API that cannot work with the Firewall service buffers.
  • You have to read into a preallocated buffer.
  • You want to use your own allocator for the buffer.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXIOBuffer::Append Method

Appends a specified number of bytes to the buffer object.

HRESULT Append(
  void const *pv,
  ULONG cb,
  ULONG *pcbWritten
);

Parameters

pv
[in] Pointer to the buffer which is appended to the buffer object.
cb
[in] The number of bytes of data to attempt to append to the buffer object.
pcbWritten
[out] Address of a ULONG variable where this method writes the actual number of bytes appended to the buffer object.

Return Values

S_OK
The data was successfully appended to the buffer object.
FWX_E_BUFFERFULL
Not all the data was appended to the buffer object because the buffer is full.

Remarks

This method does not resize the buffer. The pcbWritten parameter is valid even if an FWX_E_BUFFERFULL error is returned.


IFWXIOBuffer::GetBufferAndSize Method

Gets the actual data from the memory buffer.

HRESULT GetBufferAndSize(
  BYTE **ppBuffer,
  DWORD *pdwSize
);

Parameters

ppBuffer
[out] Address of a variable that receives a pointer to the buffer.
pdwSize
[out] Pointer to DWORD data type that receives the size, in bytes, of the buffer.

Return Values

S_OK
The method succeeded.
E_NOTIMPL
Returned if the client and server are not in the same apartment. This may happen if the filter is not an in-proc server.


IFWXIOBuffer::GetBufferSizes Method

Gets the allocated and actual buffer sizes.

HRESULT GetBufferSizes(
  LPDWORD pdwAlocatedSize,
  LPDWORD pdwActualSize
);

Parameters

pdwAlocatedSize
Pointer to variable that receives the allocated buffer size.
pdwActualSize
Pointer to variable that receives the actual buffer size.

Return Values

S_OK
The method succeeded.
E_POINTER
Null pointer argument.


IFWXIOBuffer::ReadAt Method

This method reads a specified number of bytes starting at a specified offset from the beginning of the buffer.

HRESULT ReadAt(
  ULONG ulOffset,
  void *pv,
  ULONG cb,
  ULONG *pcbRead
);

Parameters

ulOffset
Specifies the starting point from the beginning of the buffer for reading data.
pv
Pointer to the buffer into which the buffer content is copied.
cb
Specifies the number of bytes to attempt to read from the byte buffer.
pcbRead
Pointer to a location where this method writes the actual number of bytes copied from the buffer. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes copied.

Return Values

S_OK
The method succeeded.
E_INVALIDARG
Invalid parameter.
E_POINTER
Null pointer argument.
FWX_E_BUFFER_FULL
The buffer is full.


IFWXIOBuffer::SendToBuffer Method

Appends a specified number of bytes starting at a specified offset from the beginning of the buffer to the given destination buffer.

HRESULT SendToBuffer(
  IFWXIOBuffer *pDestinationBuffer,
  ULONG ulOffset,
  ULONG cb,
  ULONG *pcbCopied
);

Parameters

pDestinationBuffer
[in] Buffer to which data will be appended.
ulOffset
[in] Specifies the starting point from the beginning of the buffer for reading data.
cb
[in] Specifies the number of bytes to attempt to append to the destination buffer.
pcbCopied
[out] Address of a ULONG variable where this method writes the actual number of bytes appended to the buffer object.

Return Values

S_OK
The method succeeded.
E_NOTIMPL
Returned if the client and server are not in the same apartment. This may happen if the filter is not an in-proc server.


IFWXIOBuffer::SetDataSize Method

Sets the actual size of the memory buffer that was used.

HRESULT SetDataSize(
  DWORD dwDataSize
);

Parameters

dwDataSize
[in] The actual size, in bytes, of the buffer that was used.

Return Values

S_OK
The data was successfully appended to the buffer object.
E_INVALIDARG
Requested size is larger than allocated size.

Remarks

When a buffer is used in a call to the IFWXSocket::Recv method, the SetDataSize method may be called if the size of available data is less than the size allocated for the buffer.

SetDataSize can be called by a filter after buffer content is manipulated directly by means of IFWXIOBuffer::GetBufferAndSize.

SetDataSize can be called by the Firewall service, when a buffer is passed to IFWXSocket::Recv, to set the number of bytes actually received.


IFWXIOCompletion

IFWXIOCompletion is the application filter interface that receives notification from the Firewall service when an asynchronous I/O send, sendto, or receive operation is completed on an IFWXSocket interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXIOCompletion Methods | Description
CompleteAsyncIO | Receives notifications from the Firewall service when an asynchronous I/O operation completes.

Implementation

This interface is implemented by the application filter.

Remarks

All overlapped operations on an IFWXSocket interface require the filter to implement this interface. When calling a method that begins an overlapped operation, the filter must pass to that method a pointer to the IFWXIOCompletion interface. The Firewall service calls the IFWXIOCompletion interface of the filter when an overlapped operation completes.

ISA has two other notification methods for overlapped operations. The IFWXExternalIOCompletion::CompleteAsyncIO notification method is used for notification when a Win32 overlapped operation completes, and the IFWXAcceptCompletion::CompleteAsyncAccept method is used for notification when the IFWXNetworkSocket::Accept method completes.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXSocket::Recv, IFWXSocket::Send, IFWXSocket::SendTo


IFWXIOCompletion::CompleteAsyncIO Method

Receives notifications from the Firewall service when an asynchronous I/O operation completes. All overlapped operations on an IFWXSocket interface require the filter to implement this interface.

The CompleteAsyncIO method is where you should implement the logic of your filter, based on the protocol in which you are working.

HRESULT CompleteAsyncIO(
  BOOL fSuccess,
  DWORD Win32ErrorCode,
  IFWXIOBuffer *pIOBuffer,
  UserContextType UserData,
  LPSOCKADDR ExternalAddress,
  INT ExternalAddressLength
);

Parameters

fSuccess
[in] Success flag. If TRUE, the I/O operation succeeded. If FALSE, it failed.
Win32ErrorCode
[in] Win32 error code. This parameter is defined only if the fSuccess parameter is FALSE.
pIOBuffer
[in] Pointer to the IFWXIOBuffer interface for the data buffer, if this is a completion for a receive method.
UserData
[in] The UserData parameter that was passed to the I/O method.
ExternalAddress
[in] Pointer to a sockaddr structure that contains the address of the external source or external destination of a UDP packet. This parameter is passed only for the IFWXSocket::Recv method on a UDP socket. The ExternalAddress parameter is NULL for TCP sockets.

The address is the source when receiving from an external socket, and the target when receiving from an internal socket.

Note that IP packets on the Internet can be made to appear as though they are authorized when they are not. Therefore, do not rely on this address for authentication.

ExternalAddressLength
[in] Length, in bytes, of the ExternalAddress parameter.

Return Values

S_OK
The method succeeded.

Any error should be handled in this method.

Remarks

Be aware that completion of a send or sendto operation indicates only that the next filter in the chain of filters received the buffer and began processing it. The buffer cannot be recycled at this point.

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them by using different values for UserData.

See Also

IFWXIOBuffer


IFWXIpFilter

IFWXIpFilter is the application filter interface that represents an IP Filter: a range of IP addresses for which a connection or socket is allowed to function. Use this interface to ensure that secondary and emulated connections are secure.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXIpFilter Methods | Description
IncludeRange | Includes a range of IP addresses in the IP filter.
ExcludeRange | Excludes a range of IP addresses from the IP filter.
IncludeFilter | Includes in the IP filter a range of IP addresses represented by an existing IP filter.
ExcludeFilter | Excludes from the IP filter a range of IP addresses represented by an existing IP filter.
IsIncluded | Checks if a particular IP address is allowed by the IP filter.
Compare | Compares the IP ranges of two IP filters.
Clone | Returns a copy of an IP filter.

Implementation

This interface is implemented by the Firewall service.

Remarks

There are situations in which an application filter is responsible for limiting what IP addresses are allowed access, including:

  • The case of a secondary inbound connection, as occurs in use of the FTP protocol. Use IFWXIpFilter in the FTP scenario to restrict the access to the inbound socket of the secondary connection. For example, an FTP application filter opens a secondary connection with a range that includes only the IP address of the FTP server. All IP packets with a source address that isn't the IP address of the FTP server will be ejected by the packet filter driver if they are addressed to the socket that FTP application filter created for the secondary connection.
  • The case of a secondary or emulated connection in a publishing scenario.

For security purposes, the application filter has to define an IP filter: a range of IP addresses for which a particular connection or socket is allowed. The IFWXIpFilter interface is where you define that range of IP addresses.

An IP filter created by using the IFWXIpFilter interface is no more than a definition of IP ranges. The mechanism that provides the filtering functionality is the ISA server packet filtering mechanism. Therefore, an IP filter defined by using IFWXIpFilter will not function unless IP packet filtering is enabled in ISA. For more information about packet filtering, see IP Packet Filtering or the ISA Server product documentation.

Note If you set the range of IP addresses equal to NULL, you are allowing all addresses to connect.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXFirewall::CreateIpFilter, IFWXConnection, IFWXNetworkSocket, IFWXSession


IFWXIpFilter::Clone Method

Returns a copy of an IP filter. The copy will contain the same ranges of IP addresses as the original.

HRESULT Clone(
  IFWXIpFilter **ppIpFilter
);

Parameters

ppIpFilter
[out] Address of a variable that receives a pointer to the IFWXIpFilter interface.


IFWXIpFilter::Compare Method

Compares the IP ranges of two IP filters.

HRESULT Compare(
  [in] IFWXIpFilter *pIpFilter
);

Parameters

pIpFilter
[in] Pointer to the IFWXIpFilter interface.

Return Values

S_OK
The ranges are equal.
S_FALSE
The ranges are not equal.


IFWXIpFilter::ExcludeFilter Method

Excludes from the IP filter a range of IP addresses represented by an existing IP filter.

HRESULT ExcludeFilter(
  IFWXIpFilter *pIpFilter
);

Parameters

pIpFilter
[in] Pointer to the IFWXIpFilter interface.


IFWXIpFilter::ExcludeRange Method

Excludes a range of IP addresses from the IP filter.

HRESULT ExcludeRange(
  IN_ADDR IP_From,
  IN_ADDR IP_To
);

Parameters

IP_From
[in] Lower end of IP Range to exclude.
IP_To
[in] Upper end of IP Range to exclude.


IFWXIpFilter::IncludeFilter Method

Includes in the IP filter a range of IP addresses represented by an existing IP filter.

HRESULT IncludeFilter(
  IFWXIpFilter *pIpFilter
);

Parameters

pIpFilter
[in] Pointer to the IFWXIpFilter interface.


IFWXIpFilter::IncludeRange Method

Includes a range of IP addresses in the IP filter.

HRESULT IncludeRange(
  IN_ADDR IP_From,
  IN_ADDR IP_To
);

Parameters

IP_From
[in] Lower end of IP Range to include.
IP_To
[in] Upper end of IP Range to include.


IFWXIpFilter::IsIncluded Method

Checks if a particular IP address is included in the ranges of those allowed by the IP filter.

HRESULT IsIncluded(
  IN_ADDR IP
);

Parameters

IP
IP address to check.

Return Values

S_OK
The address is included.
S_FALSE
The address is not included.

Remarks

Based on the value returned by IFWXIpFilter::IsIncluded, you can decide whether to initiate a connection. There is no automatic effect upon the connection. For example, you may use this method in the following way:

  1. Call IFWXConnection::GetIpFilter on a connection object, such as a listening connection object.
  2. Use IFWXIpFilter::IsIncluded to check if a specific IP address is included in the ranges specified by the filter.
  3. If the address is not included in the range, you can decide to not initiate the connection.


IFWXNetworkSocket

The IFWXNetworkSocket interface is the Firewall service socket interface, and is derived from the IFWXSocket interface. The implementation uses the dynamic packet filter functionality of ISA Server to automatically open a port in the packet filter when necessary, and close it when the socket is closed. For more information, see IP Packet Filtering.

Note Before releasing this interface, you must call IFWXSocket::Close or IFWXSocket::Shutdown on it.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSocket Methods | Description
Send | Sends a buffer asynchronously.
SendTo | Sends a buffer asynchronously to a specific address, on UDP sockets.
Recv | Receives a buffer asynchronously.
Shutdown | Shuts down the socket (half close).
Close | Closes the socket.

IFWXNetworkSocket Methods | Description
Connect | Establishes a connection to a specified socket. This method is similar to the Windows Sockets (Winsock) connect function, described in MSDN.
Bind | Associates a local address with a socket. This method is similar to the Winsock bind function, described in MSDN.
GetSockName | Gets the local name of a socket. This method is similar to the Winsock getsockname function, described in MSDN.
GetPeerName | Gets the remote name of a socket. This method is similar to the Winsock getpeername function, described in MSDN.
Listen | Listens on a TCP socket.
GetSockOpt | Gets a socket option. This method is similar to Winsock getsockopt function, described in MSDN.
SetSockOpt | Sets a socket option. This method is similar to the Winsock setsockopt function, described in MSDN.
Accept | Asynchronously permits a connection on a listening socket. This method is similar to the Winsock accept function, described in MSDN.
SetPacketFilterOptions | Sets options for the dynamic packet filtering used with this socket.
GetIpFilter | Gets a copy of the IP filter object for the socket.
SetIpFilter | Sets the IP filter for the socket.

Remarks

A socket object that implements this interface can be created by by using IFWXFirewall::CreateNetworkSocket or IFWXSession::CreateNetworkSocket. The nature of the socket is determined by which of these two methods was used to create the object. A socket created by using IFWXFirewall::CreateNetworkSocket is not user specific. An example of a socket that should not be user specific is a listening socket. To create a user-specific socket, use IFWXSession::CreateNetworkSocket. For more information, see Socket Implementation in ISA.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXNetworkSocket::Accept Method

Asynchronously accepts a connection on a listening socket.

HRESULT Accept(
  IFWXAcceptCompletion *pIFWXAcceptCompletion,
  UserContextType UserData
);

Parameters

pIFWXAcceptCompletion
[in] Pointer to the IFWXAcceptCompletion interface. This interface receives a notification when the call to the Accept method completes.
UserData
[in] An opaque value to pass to the IFWXAcceptCompletion::CompleteAsyncAccept notification method. This parameter provides a context to the notification.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them by using different values for UserData.

This method is similar to the Winsock accept function, which is described in MSDN.


IFWXNetworkSocket::Bind Method

Binds a socket to a specific address.

HRESULT Bind(
  LPSOCKADDR Address,
  INT AddressLength,
  IFWXIpFilter *pIpFilter
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to assign to the socket.
AddressLength
[in] Length, in bytes, of the Address parameter.
pIpFilter
[in] Pointer to the IFWXIpFilter interface. The socket that is bound by using IFWXNetworkSocket::Bind will be restricted according to that IP filter. If you specify NULL for this parameter, the socket will not be restricted.

Remarks

This method is similar to the Winsock bind function, which is described in MSDN.


IFWXNetworkSocket::Connect Method

Connects a socket to a specific address.

HRESULT Connect(
  LPSOCKADDR Address,
  DWORD AddressLength
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to connect to.
AddressLength
[in] Length, in bytes, of the Address parameter.

Remarks

This method is similar to the Winsock connect function, which is described in MSDN.


IFWXNetworkSocket::GetIpFilter Method

Gets a copy of the IP filter object for the socket. Returns NULL if the connection is not limited to a range of IP addresses.

HRESULT GetIpFilter(
  IFWXIpFilter **ppIpFilter
);

Parameters

ppIpFilter
[out] Address of a variable that receives a pointer to the IFWXIpFilter interface.

Remarks

Because the returned object is a copy, modifying the copy will not affect the socket object.

See Also

IFWXIpFilter


IFWXNetworkSocket::GetPeerName Method

Gets the remote address of a socket.

HRESULT GetPeerName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to the address of a sockaddr structure that receives the address (name) of the peer.
AddressLength
[in, out] On input, specifies the size, in bytes, of the Address buffer. On output, receives the buffer size, in bytes, needed to hold the address.

Remarks

Used when a connection has been requested from outside the network, and you want to identify it. This method is similar to the Winsock getpeername function, which is described in MSDN.

Return Values

S_OK
The method succeeded.
HRESULT_FROM_WIN32(WSAEFAULT)
The name or the namelen parameter is not a valid part of the user address space, or the namelen parameter is too small.


IFWXNetworkSocket::GetSockName Method

Gets the local address of a socket.

HRESULT GetSockName(
  LPSOCKADDR Address,
  LPINT AddressLength
);

Parameters

Address
[out] Pointer to a Winsock sockaddr structure that receives the socket address (name).
AddressLength
[in, out] On input, specifies the size, in bytes, of the Address buffer. On output, receives the buffer size, in bytes, needed to hold the address.

Return Values

S_OK
The method succeeded.
HRESULT_FROM_WIN32(WSAEFAULT)
The name or the namelen parameter is not a valid part of the user address space, or the namelen parameter is too small.
HRESULT_FROM_WIN32(WSAEINVAL)
The socket has not been bound to an address with bind.

Remarks

This method is similar to the Winsock getsockname function, which is described in MSDN.


IFWXNetworkSocket::GetSockOpt Method

Gets a socket option.

HRESULT GetSockOpt(
  int level,
  int optname,
  char *optval,
  int optlen
);

Parameters

level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP.
optname
[in] Socket option for which the value is to be set.
optval
[in] A pointer to the buffer in which the value for the requested option is supplied.
optlen
[in, out] Size, in bytes, of the optval buffer.

Remarks

This method is similar to the Winsock getsockopt function, which is described in MSDN.


IFWXNetworkSocket::Listen Method

Listens on a TCP socket.

HRESULT Listen(
  INT Backlog
);

Parameters

Backlog
[in] Maximum length of the queue of pending connections. This is the same as the backlog parameter of the Winsock listen function, described in MSDN.

Remarks

The Listen method indicates to the network that you are willing to accept connections to the port for which you have a bind.


IFWXNetworkSocket::SetIpFilter Method

Sets the IP filter for the socket. Either sets a new IP filter if there had not been one, or replaces the current IP filter with a new one.

HRESULT SetIpFilter(
  IFWXIpFilter *pIpFilter
);

Parameters

pIpFilter
[in] Pointer to the IFWXIpFilter interface. Setting this parameter equal to NULL will result in no IP address restrictions for this socket.

See Also

IFWXIpFilter


IFWXNetworkSocket::SetPacketFilterOptions Method

Sets options for dynamic packet filtering.

HRESULT SetPacketFilterOptions(
  BOOL fDiscardInbound,
  DWORD Reserved
);

Parameters

fDiscardInbound
[in] Discard-inbound flag. If TRUE, an opening in the packet filter is not created for inbound packets. If FALSE, an opening is created for inbound packets.
Reserved
Reserved for future use. This parameter must be zero.

Return Values

S_OK
The method succeeded.
E_INVALIDARG
Invalid parameter.
FWX_E_TERMINATING
The socket is already closed.

Remarks

This method can be called to restrict the opening of dynamic packet filters for use with this socket object. By default, the Firewall service creates a dynamic filter for communication through this socket. Use this method to avoid opening packet filters for this socket. For example, to limit a connection to internal clients, creation of openings in packet filters for incoming UDP datagrams or incoming TCP connections can be disabled by using this method.


IFWXNetworkSocket::SetSockOpt Method

Sets a socket option.

HRESULT SetSockOpt(
  int level,
  int optname,
  char *optval,
  int optlen
);

Parameters

level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP.
optname
[in] Socket option for which the value is to be set.
optval
[in] A pointer to the buffer where the value for the requested option is supplied.
optlen
[in] Size, in bytes, of the optval buffer.

Remarks

This method is similar to the Winsock setsockopt function, which is described in MSDN.


IFWXOverlapped

The IFWXOverlapped interface is used to hook into the I/O completion port of the Firewall service, for asynchronous I/O with Win32 files. You can hook into the completion port thread pool by linking a handle to the completion port (call the IFWXFirewall::HookToCompletionPort method). Overlapped Win32 functions must then be called with the Winsock structure OVERLAPPED returned by this interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXOverlapped Methods | Description
GetOverlapped | Gets a pointer to an overlapped structure.
SetNotificationInterface | Sets the callback for the completion of the overlapped I/O.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXExternalIOCompletion


IFWXOverlapped::GetOverlapped Method

Gets a pointer to a Winsock OVERLAPPED structure to use with Win32 overlapped functions.

HRESULT GetOverlapped(
  LPOVERLAPPED *ppov
);

Parameters

ppov
[out] Pointer to a variable that receives a pointer to an OVERLAPPED structure.

Remarks

The handle used with the OVERLAPPED structure must first be hooked into the completion port of the Firewall service by using the IFWXFirewall::HookToCompletionPort method.


IFWXOverlapped::SetNotificationInterface Method

Sets the callback for the completion of the overlapped I/O.

HRESULT SetNotificationInterface(
  IFWXExternalIOCompletion *piExternalIOCompletion,
  UserContextType UserData
);

Parameters

piExternalIOCompletion
[in] Pointer to an IFWXExternalIOCompletion interface that is notified when the overlapped I/O is completed.
UserData
[in] An opaque value to pass to the IFWXExternalIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification.

Remarks

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them by using different values for UserData.


IFWXSession

The Firewall service implements the IFWXSession interface on the session object.

The session object implements session-specific functions that impersonate the user account, test access-control lists (ACLs) against the session user, get information about the client computer, and perform protocol operations.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSession Methods | Description
GetClientAddress | Returns the address of the user.
GetClientMachineName | Returns the name of the user's computer.
ImpersonateClient | Impersonates the user's account.
RevertToSelf | Undoes impersonation.
AccessCheck | Checks the user's permission against the ACL of a filter installed protocol.
HostAccessCheck | Checks the user's permission to access a specified host.
AllowFutureConnect | Prepares for a secondary connection by a client.
BindForClient | Prepares for an inbound secondary connection for a Firewall service or SecureNAT client. Makes a bind on behalf of a client.
EmulateClientBind | Prepares for a primary inbound connection to a SecureNAT client.
GetSessionFlags | Gets the state of the session.
RedirectConnections | Redirects an internal Firewall service interface connection to a given address.
AttachFilter | Causes a filter to be attached to the session.
SetDataFilterFactory | Sets a data filter class factory for an event.
RetroactiveAllowBind | Allows inbound connections or packets for a bind operation that already took place.
EnableInternalAddressTranslation | Enables or disables address translation for inbound connections.
CreateNetworkSocket | Creates a TCP/IP socket that is associated with this session.
GetHostByName | Retrieves host information corresponding to a host name.
GetHostByAddr | Retrieves host information corresponding to an address.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSession::AccessCheck Method

Checks the permission of the session user to use a protocol that was previously registered by calling the IFWXFilterAdmin::RegisterProtocolForFilter method.

HRESULT AccessCheck(
  REFGUID ProtocolGuid
);

Parameters

ProtocolGuid
[in] GUID identifying the protocol to check.

Return Values

S_OK
The user is in the ACL; that is, the user has permission.
S_FALSE
The user is not in the ACL; that is, the user was denied access.
Error code
The method failed.

Remarks

Though you would typically use this method to check a user's permission to use a protocol that was registered by calling IFWXFilterAdmin::RegisterProtocolForFilter, AccessCheck Method can be used to check a user's access to any protocol.


IFWXSession::AllowFutureConnect Method

Allows a client to make secondary outbound connections.

HRESULT AllowFutureConnect(
  LPSOCKADDR Address,
  DWORD AddressLength,
  LPSOCKADDR ProxyExternalAddress,
  DWORD ProxyExternalAddressLength,
  INT Protocol,
  DWORD dwFlags,
  REFGUID ProtocolGuid,
  IFWXSessionFilter *pSessionFilter,
  IUnknown *punkContext,
  IFWXFirewallAction **ppFirewallAction
);

Parameters

Address
[in] Pointer to a sockaddr structure that contains the address to which the client will connect.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
ProxyExternalAddress
[in] Pointer to a sockaddr structure that contains the proxy external address used for the connection. This is useful in the case of multihomed proxy servers. Requesting a specific address ensures that a secondary connection uses the same proxy IP address as the primary. This parameter can be NULL, defaulting to INADDR_ANY and 0 (any port).
ProxyExternalAddressLength
[in] Length, in bytes, of the ProxyExternalAddress structure.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The connection will use the TCP protocol.
FWX_PROTOCOL_UDP | The connection will use the UDP protocol.

dwFlags
[in] Connection flags. This parameter can be a combination of the following connection flags:
Value | Description
FWX_FLAG_ADDRESS_BASED | The permission should be associated with the client address, not the client session. This is necessary if the protocol involves connections that are intiated by different processes.
FWX_FLAG_ALLOW_MULTIPLE | By default, a single outbound connection is expected. If this flag is specified, multiple connections to the same address will be possible.
FWX_FLAG_TIMEOUT | The client is expected to use the permission within approximately one minute of the call. If the client does not make the connection, the permission automatically expires.
FWX_FLAG_NO_KERNEL_MODE | The connection is forced to go through user-mode code, even if currently there seems to be no reason not to use kernel-mode for the connection.
FWX_FLAG_BIDIRECTIONAL | Permission is also granted for packets coming back from the destination socket to the sending socket. This flag is only valid for UDP.

ProtocolGuid
[in] GUID identifying the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
pSessionFilter
Optional. [in] Pointer to the IFWXSessionFilter object. Use with the punkContext parameter to receive the fwx_EstablishedConnection event from the Firewall service.
punkContext
Optional. [in] Provides user context information regarding the connection. Use with the pSessionFilter parameter to receive the fwx_EstablishedConnection event from the Firewall service. Specify NULL if the fwx_EstablishedNotification notification is not required.
ppFirewallAction
[out] Address of a variable that receivespointer to the IFWXFirewallAction interface on the Firewall service action object created as a result of this call. This parameter can be NULL.

Return Values

S_OK
The method succeeded.
FWX_E_PROTOCOL_RULES_DENIED
The connection will not be allowed because it conflicts with the protocol rules for the session user.
FWX_E_SITE_AND_CONTENT_RULES_DENIED
The connection will not be allowed because it conflicts with the site and content rules for the session user.

Remarks

A filter should call this method when it detects, by inspecting another (usually the "primary") connection, that the client needs to make a TCP connection to the server, or to send one or more UDP datagrams to that server. This is usually known when the server sends an address to the client. For example, when an FTP server sends the following, it is instructing the client to connect to address 198.105.232.1 on port 1046.

227 Entering Passive Mode (198,105,232,1,4,22)

The call allows an outbound connection from the client denoted by the session object (the IP address given by the GetClientAddress method) to the requested address.

Using this method is preferable to defining a secondary port, or port range in a protocol definition, and to handling all connect events and calling IFWXConnection::SetProtocol or IFWXConnection::Deny, as appropriate.

It is impossible to attach a data filter to a kernel-mode connection. For this reason, the Firewall service will not make a kernel-mode connection if a data filter is expected to be set on the connection or if a filter is registered for the resulting connection event. When a filter calls SetDataFilterFactory, the decision has already been made and cannot be modified. A filter that is going to call SetDataFilterFactory for the resulting connection should specify FWX_FLAG_NO_KERNEL_MODE. A filter that already called SetDataFilterFactory for the resulting connection is not required to specify this flag.

The FWX_FLAG_TIMEOUT flag cannot be specified in conjunction with the FWX_FLAG_ALLOW_MULTIPLE flag.

See Also

IFWXConnection::SetProtocol, IFWXFirewallAction, IFWXSession::GetClientAddress, IFWXSession::SetDataFilterFactory, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::AttachFilter Method

Causes a filter to be loaded for this session even if the initial event for this filter did not yet happen. If the filter has already attached a session filter for this session, nothing happens; otherwise, the filter's IFWXFilter::AttachToSession method is called.

HRESULT AttachFilter(
  REFCLSID guidFilter
);

Parameters

guidFilter
[in] CLSID of the filter to load.

Return Values

S_OK
The method succeeded.
REGDB_E_CLASSNOTREG
The GUID does not represent a valid filter.


IFWXSession::BindForClient Method

Bind on the Firewall service on behalf of the client.

The BindForClient method permits a SecureNAT client to receive a secondary inbound connection. It also allows a client application — for which the Firewall client component failed to create a remote socket for a bind call — to receive an inbound connection. The processing done by the filter can be the same in both cases. The only difference is that in the case of a SecureNAT client, the filter knows that the client is sending a private address that has to be translated. For a Firewall client, the filter has to verify that the client is sending an internal address on an external interface.

HRESULT BindForClient(
  LPSOCKADDR ClientAddresses[],
  DWORD ClientAddressLength,
  LPSOCKADDR ProxyAddress,
  DWORD ProxyAddressLength,
  INT Protocol,
  DWORD dwNumberOfAddresses,
  DWORD dwFlags,
  INT Backlog,
  REFGUID ProtocolGuid,
  IFWXSessionFilter *pSessionFilter,
  IUnknown *punkContext,
  IFWXIpFilter *pIpFilter,
  PFWXICONNECTION ConnectionArray[]
);

Parameters

ClientAddresses[]
[in] Pointer to an array of pointers to sockaddr structures that contain the addresses that the client used. The array contains dwNumberOfAddresses pointers. In rare cases, a client address is not yet known. In these cases, it is possible to specify an address of all zeros. After the client address is known, call the IFWXConnection::SetClientAddress method.
ClientAddressLength
[in] Length, in bytes, of the addresses pointed to by the ClientAddresses parameter.
ProxyAddress
[in, out] Pointer to a sockaddr structure that contains the address to which the filter is to bind. This is usually an external IP address of the proxy, and PORT_ANY. On return, this parameter receives the actual address to which the filter binds.
ProxyAddressLength
[in] Length, in bytes, of the ProxyAddress parameter.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The request is for a TCP socket.
FWX_PROTOCOL_UDP | The request is for a UDP socket.

dwNumberOfAddresses
[in] Number of consecutive addresses to assign.
dwFlags
Connection flags. This parameter can be any combination of the following flag values:
Value | Description
FWX_FLAG_ALLOW_MULTIPLE | By default, only a single connection is expected on a listening TCP socket (for example, FTP). If more than one connection to the same address and port is expected, specify this flag. For UDP sockets, set the flag if datagrams are expected from more than one source. If only a single source will send datagrams, do not set this flag.
FWX_FLAG_TIMEOUT | When this flag is set, UDP connections are closed automatically when they are detected to be idle. For TCP, when no connection is accepted within the timeout period of approximately one minute, the listening connection is closed. When not set, the calling filter must call the IFWXConnection::Kill method to terminate the connection.
FWX_FLAG_NO_KERNEL_MODE | The connection is forced to go through user-mode code, even if currently there seems to be no reason not to use kernel-mode for the connection.
FWX_FLAG_BIDIRECTIONAL | Permission is also granted to send packets back to destinations that recently sent packets to the socket. This flag is only valid for UDP.

Backlog
[in] The backlog to be used by IFWXNetworkSocket::Listen. The Backlog parameter specifies the maximum length of the queue of pending connections. This is the same as the backlog parameter of the Winsock listen function, described in MSDN.
ProtocolGuid
[in] GUID identifying the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
pSessionFilter
Optional. [in] Pointer to the IFWXSessionFilter object. Use with the punkContext parameter to receive the fwx_EstablishedConnection event from the Firewall service. This parameter can be NULL, in which case no notification will be provided.
punkContext
Optional. [in] Provides user context information regarding the connection. Use with the pSessionFilter parameter to receive the fwx_EstablishedConnection event from the Firewall service. This parameter can be NULL. Specify NULL if the fwx_EstablishedNotification notification is not required.
pIpFilter
Pointer to the IFWXIpFilter object. All connections that are created by BindForClient will be restricted by the IFWXIpFilter pointed to by this parameter. If you specify NULL for this parameter, the connection will not be restricted at all by an IFWXIpFilter object. Similarly, if you do not set a value for this parameter, all IP addresses will be allowed access. If you specify a zero value for this parameter, all IP addresses will be blocked.
ConnectionArray[]
[out] Pointer to an array of dwNumberOfAddresses IFWXConnection interface pointers. The array is filled with pointers to the IFWXConnection interfaces on the resulting connection objects. The array contains dwNumberOfAddresses pointers.

Return Values

S_OK
The method succeeded.
FWX_E_PROTOCOL_RULES_DENIED
The protocol rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.
HRESULT_FROM_WIN32(WSAEADDRINUSE)
The proxy address requested is already in use.
HRESULT_FROM_WIN32(WSAEADDRNOTAVAIL)
The specified address is not a valid address for this computer.

Remarks

This method should be called by a filter that enables a specific protocol when upon detecting, by inspecting the primary connection, that the client is expecting a secondary inbound connection (either TCP or UDP). This is usually known when the client sends its address to the server as part of the protocol. For example, when an FTP client sends the following, it is instructing the server to connect to the address 10.0.0.8 on port 1553:

PORT 10,0,0,8,6,17

A SecureNAT editor detecting such a command should call the BindForClient method, which binds an external socket and associates it with the client socket.

The call allows inbound connections to the client denoted by the session object. The ClientAddress parameter will be the address and port sent by the client, and will usually have the same IP address as that given by the GetClientAddress method.

Like other bind requests, any filter registered for the fwx_Bind_* events is notified about this bind and has an opportunity to deny it. The filter may also install a data filter or even emulate the bind.

If no data filter is installed, the Firewall service handles this connection in kernel mode. A connection handled in kernel mode is less delayed and uses fewer CPU and memory resources on the Firewall service.

The filter is expected to modify the control stream and send a modified address to the server. For the FTP example, the PORT command will be modified to reflect the address and port returned in the ProxyAddress parameter.

This method also allows multiple consecutive ports to be assigned and returns connection objects that can be used to control the resulting connections.

When dwNumberOfAddresses is greater than 1, a set of consecutive ports is allocated. The lowest port allocated is a multiple of dwNumberOfAddresses. The set of addresses specified in ConnectionArray does not have to be consecutive. The first address in ConnectionArray corresponds to the lowest port, the second to the next port, and so forth.

On input, the ProxyAddress parameter can be used to force binding to a specific interface of the Firewall service, and to force a specific port (only when dwNumberOfAddresses is 1). On output, the ProxyAddress is filled with the bound Firewall service address. When dwNumberOfAddresses is greater than 1, the address with the lower port number is returned.

If FWX_FLAG_TIMEOUT is not specified, the connection object will not be deleted until the filter calls the IFWXConnection::Kill method.

The FWX_FLAG_TIMEOUT flag cannot be specified together with the FWX_FLAG_ALLOW_MULTIPLE flag.

It is impossible to attach a data filter to a kernel-mode connection. For this reason, the Firewall service will not make a kernel-mode connection if a data filter is expected to be set on the connection, or if a filter is registered for the resulting connection event. When a filter calls SetDataFilterFactory, the decision has already been taken and cannot be modified. A filter that is going to call SetDataFilterFactory for the resulting connection should specify FWX_FLAG_NO_KERNEL_MODE. A filter that already called SetDataFilterFactory for the resulting connection is not required to specify this flag.

See Also

IFWXConnection, IFWXIpFilter IFWXConnection::Kill, IFWXSession::BindForClient, IFWXConnection::SetClientAddress, IFWXSession::SetDataFilterFactory, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::CreateNetworkSocket Method

Creates a TCP/IP socket that is associated with this session.

HRESULT CreateNetworkSocket(
  INT Protocol,
  IFWXNetworkSocket **piSocket
);

Parameters

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The method will create a TCP socket.
FWX_PROTOCOL_UDP | The method will create a UDP socket.

piSocket
[out] Address of a variable that receives a pointer to the IFWXNetworkSocket interface.

Return Values

S_OK
The socket was created.
E_OUTOFMEMORY
Insufficient memory or resources to process the event; the socket was not created.
HRESULT_FROM_WIN32(win32 error code)
Winsock or Win32 error code. The method failed.

Remarks

The socket created by this method is user-specific, and its activity obeys the policy rules for the session. Connections are logged as if they were performed by the session's user.

To create a socket that is not user specific, use IFWXFirewall::CreateNetworkSocket.


IFWXSession::EmulateClientBind Method

Allows a client that did not create a remote bind to receive a primary inbound connection.

HRESULT EmulateClientBind(
  LPSOCKADDR ClientAddress,
  DWORD ClientAddressLength,
  LPSOCKADDR ProxyAddress,
  DWORD ProxyAddressLength,
  INT Protocol,
  REFGUID ProtocolGuid,
  IFWXConnection **piConnection
);

Parameters

ClientAddress
[in] Pointer to a sockaddr structure that contains the address that the client used.
ClientAddressLength
[in] Length, in bytes, of the ClientAddress parameter.
ProxyAddress
[in] Pointer to a sockaddr structure that contains the address to which the filter is emulating bind. This is usually an external IP address of the Firewall service and a specific port number. The EmulateClientBind method does not really bind to that address. The address is used for the bind event generated.
ProxyAddressLength
[in] Length, in bytes, of the ProxyAddress parameter.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The request is for a TCP socket.
FWX_PROTOCOL_UDP | The request is for a UDP socket.

ProtocolGuid
[in] GUID identifying the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
piConnection
[out] Pointer to a buffer that receives the address of the resulting connection object.

Remarks

This method should be called by a filter whose purpose is to enable a specific protocol. The filter uses this method when it needs to forward a primary connection made from an external source to a local computer that did not make a remote bind through the Firewall service. For example, this could be a local computer that is not a Firewall client.

This method will usually be called by a filter that is listening on some well-known port when it receives a connection. The filter decides (based on the source address, data exchange with the caller, a hard-coded address, and so on) that this call should be forwarded to some internal client.

The filter cannot use the BindForClient method because the well-known port is already in use and the connection was already made.

This method creates a connection object on which the caller can call the IFWXConnection::EmulateConnection method and forward the connection to the client.

Like other bind requests, any filter registered for the fwx_Bind_* events is notified about this bind and has an opportunity to deny it. It may also install a data filter. Other filters cannot emulate this bind because the caller is already emulating it.

See Also

IFWXConnection::EmulateConnection, IFWXSession::BindForClient, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::EnableInternalAddressTranslation Method

Enables or disables internal address translation.

HRESULT EnableInternalAddressTranslation(
  BOOL fEnable
);

Parameters

fEnable
[in] A nonzero value enables translation of external addresses to internal addresses. Zero disables the translation.

Return Values

S_OK
The method succeeded.
WFX_E_NOT_SUPPORTED
Modifying this property is not allowed for this session.

Remarks

This method can only be used for sessions created with CreatePrivateSession. By default, when a filter calls BindForClient, the address of the external host connecting will be seen by the internal client. In some circumstances this is not desirable. When internal address translation is enabled, the internal address of the Firewall service will be used instead.

See Also

IFWXSession::BindForClient


IFWXSession::GetClientAddress Method

Gets the address of the user.

HRESULT GetClientAddress(
  LPSOCKADDR Address,
  LPDWORD AddressLength
);

Parameters

Address
[out] Pointer to a sockaddr structure that receives the client address (port = 0 for AF_INET).
AddressLength
[in, out] Pointer to the length, in bytes, of the address specified in the Address parameter. On return, AddressLength receives the actual size of the address returned in Address.


IFWXSession::GetClientMachineName Method

Gets the name of the client computer, if it is available. The Firewall client DLL passes the computer name in the request. The name is not available for SecureNAT clients.

HRESULT GetClientMachineName(
  LPSTR *pszMachineName
);

Parameters

pszMachineName
[out] Address of a buffer that receives a pointer to the requested computer name string. The caller must free the pszMachineName buffer by using the CoTaskMemFree function.


IFWXSession::GetHostByAddr Method

Retrieves host information corresponding to an address.

HRESULT GetHostByAddr(
  const char *addr,
  int len,
  int type,
  char *buf,
  int *buflen
);

Parameters

addr
[in] Pointer to the network address for the host. Host addresses are stored in network byte order.
len
[in] Length of the address.
type
[in] Type of the address.
buf
[out] Pointer to the data area to receive the hostent data. The data area must be larger than the size of a hostent structure because the supplied data area is used by Windows Sockets to contain a hostent structure and all of the data referenced by members of the hostent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
buflen
[in, out] On input, specifies the size of data area for the buf parameter. If the buffer is too small, the error code ERROR_INSUFFICIENT_BUFFER is returned and the buflen parameter receives the size of the required buffer.

Return Values

S_OK
The method was successful. The buffer was filled with the host information.
HRESULT_FROM_WIN32(WSAENOBUFS)
Insufficient buffer space is available. (The buffer pointed to by buf is not large enough to contain the host information.)
HRESULT_FROM_WIN32(WSAHOST_NOT_FOUND)
Authoritative answer host not found.
HRESULT_FROM_WIN32(WSATRY_AGAIN)
A nonauthoritative host not found, or SERVERFAIL.
HRESULT_FROM_WIN32(WSANO_DATA)
Valid name, no data record of requested type.

Remarks

Unlike the IFWXFirewall::GetHostByAddr method, this method checks permissions, and site and content rules, prior to providing the address. If there are no permissions, or if the site and content rules do not allow access, the host information will not be provided. This method also logs the name resolution and can use autodial to dial out for the name resolution.


IFWXSession::GetHostByName Method

Retrieves host information corresponding to a host name. This method is similar to the WinSock gethostbyname method.

HRESULT GetHostByName(
  const char *name,
  char *buf,
  int *buflen
);

Parameters

name
[in] Pointer to the null-terminated name of the host.
buf
[out] Pointer to the data area to receive the hostent data. The data area must be larger than the size of a hostent structure because the supplied data area is used by Windows Sockets to contain a hostent structure and all of the data referenced by members of the hostent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
buflen
[in, out] On input, specifies the size of data area for the buf parameter. If the buffer is too small, the error code ERROR_INSUFFICIENT_BUFFER is returned and the buflen parameter receives the size of the required buffer.

Return Values

S_OK
Success, the buffer was filled with the host information.
HRESULT_FROM_WIN32(WSAENOBUFS)
Insufficient buffer space is available. (The buffer pointed to by buf is not large enough to contain the host information.)
HRESULT_FROM_WIN32(WSAHOST_NOT_FOUND)
Authoritative answer host not found.
HRESULT_FROM_WIN32(WSATRY_AGAIN)
A nonauthoritative host not found, or SERVERFAIL.
HRESULT_FROM_WIN32(WSANO_DATA)
Valid name, no data record of requested type.

Remarks

Unlike the IFWXFirewall::GetHostByName method, this method checks permissions, and site and content rules, prior to providing the address. If there are no permissions, or if the site and content rules do not allow access, the host information will not be provided. This method also logs the name resolution and can use autodial to dial out for the name resolution.


IFWXSession::GetSessionFlags Method

Gets flags that provide information about the session.

HRESULT GetSessionFlags(
  LPDWORD pOutputFlags
);

Parameters

pOutputFlags
[out] Pointer to variable that receives the session flags. The flags can be a combination of the following values:
Value | Description
FWX_SESSION_NAT | The session is by using SecureNAT (not a Firewall service control channel).
FWX_SESSION_PRIVATE | The session was created by a filter by using IFWXFirewall::CreatePrivateSession.
FWX_SESSION_AUTHENTICATED | The Firewall service authenticated the session.
FWX_SESSION_TERMINATED | The session was terminated and is no longer valid.

See Also

IFWXFirewall::CreatePrivateSession


IFWXSession::HostAccessCheck Method

By using the Site and Content Rules, this method checks the permission of the session user to access a specified host.

HRESULT HostAccessCheck(
  LPHOSTENT Hostent,
  LPCSTR pszPath,
  LPCSTR pszMime,
  DWORD dwFlags
);

Parameters

Hostent
[in] Pointer to a buffer containing a hostent structure to be checked.
pszPath
[in] Pointer to the path to be checked. This parameter may be NULL if path is unknown or irrelevant.
pszMime
[in] Pointer to string containing the MIME data type (such as "text/html") to be checked. This parameter can be NULL if the MIME type is unknown or irrelevant.
dwFlags
[in] Optional. HostAccessCheck flags. This parameter can be a combination of the following values, or 0 if neither of the options apply:
Value | Description
FWX_FLAG_FWX_FLAG_USE_MIME | The pszMime parameter is currently NULL, but may be known later. If this flag is specified, and the pszMime parameter is NULL and the MIME type is required for processing of the rules, FWX_E_MIME_NEEDED will be returned.
FWX_FLAG_USE_EXTENTION | Use the extension of the pszPath parameters for content filtering.

Return Values

S_OK
The user allowed to access the host.
S_FALSE
The user is denied access to the host.
FWX_E_MIME_NEEDED
The FWX_FLAG_FWX_FLAG_USE_MIME was specified, the pszMime parameter was NULL, and the MIME type is required to complete the processing of the rules.
Error code
The method failed.

Remarks

The hostent structure may contain names or addresses, or both names and addresses. Access is checked based on the information available in the hostent structure.


IFWXSession::ImpersonateClient Method

Calls IFWXImpersonator::Impersonate so that a filter can impersonate the authenticated user for this session.

HRESULT ImpersonateClient()

Return Values

S_OK
The user is allowed to access the host.
FWX_E_NOT_AUTHENTICATED
Could not impersonate because the session is not authenticated.

Remarks

This function will fail if the current session user is not authenticated. This could be either because the session belongs to a SecureNAT client, or because the Firewall service currently does not require authentication.

Authentication can be forced by adding a rule that requires authentication, for example, a rule that denies a specific user access to a particular site. Authentication can also be forced by setting the default rule to apply to the group Everyone instead of to Any request.

This method is used specifically by application filters for sessions created by the Firewall service or by other filters. Impersonation on behalf of the Firewall service for a session created by a particular filter is performed by that same filter through the IFWXImpersonator interface.

See Also

RevertToSelf


IFWXSession::RedirectConnections Method

Enables connections by using a local, internal Firewall service address.

HRESULT RedirectConnections(
  LPSOCKADDR ConnectAddresses[],
  DWORD ConnectAddressLength,
  DWORD dwNumberOfAddresses,
  LPSOCKADDR InternalAddress,
  LPDWORD InternalAddressLength,
  LPSOCKADDR ProxyExternalAddress,
  DWORD ProxyExternalAddressLength,
  INT Protocol,
  DWORD dwFlags,
  REFGUID ProtocolGuid,
  IFWXSessionFilter *pSessionFilter,
  IUnknown *punkContext,
  PIFWXFIREWALLACTION FirewallActionArray[]
);

Parameters

ConnectAddresses[]
[in] Pointer to an array of pointers to sockaddr structures that contain the addresses to which the client connections will be redirected.
ConnectAddressLength
[in] Length, in bytes, of the addresses pointed to by the ConnectAddresses parameter.
dwNumberOfAddresses
[in] Number of addresses in the ConnectAddresses array.
InternalAddress
[in] Pointer to a sockaddr structure that contains the address to which the client should connect instead of ConnectAddresses. This would be an internal IP address of the Firewall service.

When dwNumberOfAddresses is more than one, consecutive ports will be allocated by the Firewall service, and this parameter will contain the address by using the lowest port.

InternalAddressLength
[in, out] Length, in bytes, of the InternalAddress parameter.
ProxyExternalAddress
[in] Pointer to a sockaddr structure that contains the proxy external address used for the connection. This is useful in the case of multihomed proxy servers. Requesting a specific address ensures that a secondary connection uses the same proxy IP address as the primary. This parameter can be NULL, defaulting to INADDR_ANY and 0 (any port).
ProxyExternalAddressLength
[in] Length, in bytes, of the ProxyExternalAddress structure.
Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The connection will use a TCP socket.
FWX_PROTOCOL_UDP | The connection will use a UDP socket.

dwFlags
[in] Connection flags. This parameter can be a combination of the following values:
Value | Description
FWX_FLAG_ALLOW_MULTIPLE | By default, a single outbound connection is expected. If this flag is specified, multiple connections to the same address will be possible.
FWX_FLAG_TIMEOUT | The client is expected to use the permission shortly after the call. If the client does not make the connection, the permission automatically expires.
FWX_FLAG_NO_KERNEL_MODE | The connection is forced to go through user-mode code, even if currently there seems to be no reason not to use kernel mode for the connection.

ProtocolGuid
[in] GUID that identifies the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
pSessionFilter
Optional. [in] Pointer to the IFWXSessionFilter object. Use with the UserContext parameter to receive the fwx_EstablishedConnection event from the proxy.
punkContext
Optional. [in] Provides user context information regarding the connection. Use with the pSessionFilter parameter to receive the fwx_EstablishedConnection event from the Firewall service. This parameter can be NULL. Specify NULL if the fwx_EstablishedNotification notification is not required.
FirewallActionArray[]
[out] Pointer to an array of IFWXFirewallAction interface pointers. The array is filled with pointers to IFWXFirewallAction interfaces to the firewall action objects created by this call. The array contains dwNumberOfAddresses pointers.

Remarks

This method is intended for use by filters that act as an application proxy that has to establish secondary connections and give the same address as the primary connection for the secondary connection.

Filters for Firewall clients and for SecureNAT clients usually use AllowFutureConnect instead.

Calling this method causes all filters that are registered for connect events on the appropriate port to be notified. If no data filters are installed, a kernel-mode NAT redirection may result.

See Also

IFWXFirewallAction, IFWXSession::AllowFutureConnect, IFWXFilterAdmin::RegisterProtocolForFilter


IFWXSession::RetroactiveAllowBind Method

Allows a Firewall client to receive a secondary inbound connection on a socket that was previously bound by the Firewall client but was not necessarily approved by the Firewall service.

HRESULT RetroactiveAllowBind(
  INT Protocol,
  LPSOCKADDR Address,
  DWORD AddressLength,
  REFGUID ProtocolGuid,
  DWORD dwFlags,
  IFWXIpFilter *pIpFilter
);

Parameters

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The bind uses the TCP protocol.
FWX_PROTOCOL_UDP | The bind uses the UDP protocol.

Address
[in] Pointer to a sockaddr structure that contains the Firewall service external address for which this request is made. The address can be INADDR_ANY. The port number must be nonzero.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
ProtocolGuid
[in] GUID that identifies the protocol of which the connection is part. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
dwFlags
[in] Connection flags. This parameter can be any combination of the following flag values:
Value | Description
FWX_FLAG_BIDIRECTIONAL | Permission is also granted to send packets back to destinations that recently sent packets to the socket. This flag is only valid for UDP.

pIpFilter
Pointer to the IFWXIpFilter object. All connections that are created by BindForClient will be restricted by the IpFilter pointed to by this parameter. If you specify NULL for this parameter, the connection will not be restricted at all by an IpFilter object. Similarly, if you do not set a value for this parameter, all IP addresses will be allowed access. If you specify a zero value for this parameter, all IP addresses will be blocked.

Return Values

S_OK
The method succeeded.
S_FALSE
The connection exists and was already allowed.
E_INVALIDARG
Invalid parameter.
HRESULT_FROM_WIN32(ERROR_NOT_FOUND)
No connection with the specified address was found.
FWX_E_TERMINATING
The (bind) connection exists, but is already terminating.
FWX_E_PROTOCOL_RULES_DENIED
The protocol rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.

Remarks

Usually a filter will know that a bind call made by a Firewall client is valid only after the bind call succeeds and the Firewall client sends the address to its peer. For this reason, the Firewall service will not fail a bind call even when the service does not allow the client inbound access. Instead, the Firewall service marks the connection and discards datagrams sent, or connection attempts to that address, unless the bind becomes valid later.

When packet filtering is enabled, an opening in the dynamic packet filter will only be created for allowed connections.


IFWXSession::RevertToSelf Method

Calls IFWXImpersonator::RevertToSelf. Reverts to self after a successful call by the filter to the IFWXSession::ImpersonateClient method to impersonate the authenticated user.

HRESULT RevertToSelf()

Remarks

This method is used specifically by application filters for sessions created by the Firewall service or by other filters. Impersonation on behalf of the Firewall service for a session created by a particular filter is performed by that same filter through the IFWXImpersonator interface.


IFWXSession::SetDataFilterFactory Method

Allows a filter to set a data filter factory for events for which the filter is not registered. This method can be used to reduce the number of events for which a filter registers.

HRESULT SetDataFilterFactory(
  ProxyEventType eProxyEvent,
  LPSOCKADDR Address,
  DWORD AddressLength,
  IClassFactory *pIClassFactory,
  DataFilterPriorityClass PriorityClass,
  IUnknown *punkFilterContext,
  DWORD dwFlags,
  IFWXFirewallAction **ppFirewallAction
);

Parameters

eProxyEvent
[in] Type of event for which a data filter is requested. This can be one of the following values from the FwxFirewallEventType enumeration:

fwx_Connect_Tcp
fwx_Bind_Udp
fwx_AcceptedConnection
fwx_Udp_Destination

Address
[in] Pointer to a sockaddr structure that contains the address and port for events which should cause a data filter to be instantiated and attached. If eProxyEvent is fwx_Connect_Tcp or fwx_Udp_Destination, the address is the remote address. If eProxyEvent is fwx_Bind_Udp or fwx_AcceptedConnection, the address is the bind address. The address must be of type AF_INET, and can be either a specific IP address or INADDR_ANY.
AddressLength
[in] Length, in bytes, of the structure pointed to by the Address parameter.
pIClassFactory
[in] Pointer to a class factory for objects that support the IFWXDataFilter interface.
PriorityClass
[in] Priority class in which the data filter created will be attached. This is a value from the FwxDataFilterPriorityClass enumerated type.
punkFilterContext
[in] Pointer to an optional interface that can be used to pass context information to the data filter. This interface will be passed to IFWXDataFilter::SetSockets. This parameter can be NULL.
dwFlags
Specifies the flags for the call. Any combination of the following values is acceptable for the dwFlags parameter.
Value | Description
FWX_FLAG_ADDRESS_BASED | The connection for which the data filter is needed may be created by a different process by using the same address.

ppFirewallAction
[out] Address of a buffer that received a pointer to the IFWXFirewallAction interface on the proxy action object created as a result of this call. This parameter can be NULL

Remarks

This method is an alternative to registering to the corresponding event, comparing the address, and calling IFWXConnection::AttachDataFilter. The Firewall service creates a data filter by using the COM interface IClassFactory, when the specified event is detected. The data filter is then attached to the appropriate connection.


IFWXSessionFilter

Each application filter must implement the IFWXSessionFilter interface. The interface is implemented by each session filter object. Each user session may have a different combination of session filters attached to it; however, each session filter is attached to a single user session.

A session-filter object is attached to a user session when the Firewall service calls the IFWXFilter::AttachToSession method.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSessionFilter Methods | Description
FirewallEventHandler | Sink for Firewall service events.
Detach | Called by the Firewall service when the session is shutting down.

Implementation

This interface is implemented by the application filter.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSessionFilter::Detach Method

Notifies the session filter to detach from a session. The session filter object should release all references it holds on the session and any related objects.

HRESULT Detach()

Return Values

S_OK
The method succeeded.
E_FAIL
The method failed. This will cause the Firewall service to generate an alert.


IFWXSessionFilter::FirewallEventHandler Method

Provides the event sink for firewall events relating to the session to which this session filter is attached.

HRESULT FirewallEventHandler(
  const FirewallEvent *pFirewallEvent
);

Parameters

pFirewallEvent
[in] Pointer to a FwxFirewallEvent structure that describes the event for which this method is called and that receives information about the event. For more information, see the documentation for each event type.

Return Values

S_OK
The filter successfully processed the event.
FWX_E_TERMINATING
The filter will not process the event because IFWXSessionFilter::Detach has already been called.
E_OUTOFMEMORY
Insufficient memory or resources to process the event. This will cause the request that generated the event to fail, although a fwx_ConnectionTerminating event will be processed.

Remarks

This method is called when an event occurs for which the filter is registered.

See Also

FwxFirewallEvent


IFWXSlowDataFilter

A data-filter object may implement the IFWXSlowDataFilter interface to prevent premature termination of the connection.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSlowDataFilter Methods | Description
OkToTerminate | Verifies that all data for this connection has been processed.

Implementation

This interface is implemented by the application filter.

Remarks

When a Firewall client application calls the Winsock WSACleanup function, the client DLL will close the Firewall service session. As a result, the Firewall service will terminate all the connections that were created in this session.

In rare circumstances, this may lead to data loss, if the client application relies on TCP/IP for receipt acknowledgement. The connection could be closed after acknowledgement of a packet receipt because the slow connection delays the receipt of the remainder of the packets. This is not an issue if the client application uses application level acknowledgement.

To prevent data loss in these cases, implement the IFWXSlowDataFilter interface.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSlowDataFilter::OkToTerminate Method

Verifies that all data for this connection has been processed.

HRESULT OkToTerminate()

Return Values

S_OK
The Firewall service can safely terminate the connection.
S_FALSE
Not all data on the connection has been processed.

Remarks

When a data filter returns S_FALSE it is indicating that the Firewall service should not terminate the connection yet. The Firewall service may call this method periodically to check the status of the connection.

This method should take into account reasonable network time-out and eventually return S_OK.


IFWXSocket

The IFWXSocket interface is the Firewall service socket interface.

Note Before releasing this interface, you must call IFWXSocket::Close or IFWXSocket::Shutdown on it.

Remarks

This interface does not necessarily correspond to a network socket but allows data filters to work with the data that is flowing through the socket by using a socket-like interface. A network socket implements the IFWXNetworkSocket interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXSocket Methods | Description
Send | Sends a buffer asynchronously.
SendTo | Sends a buffer asynchronously to a specific address, on UDP sockets.
Recv | Receives a buffer asynchronously.
Shutdown | Shuts down the socket (half close).
Close | Closes the socket.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXSocket::Close Method

Closes the socket.

HRESULT Close(
  BOOLEAN fAbortive
);

Parameters

fAbortive
[in] Close-type flag. If TRUE, the connection will be hard-closed (RST packet). If FALSE, it will be closed gracefully (FIN packet).

Remarks

A hard close is done by setting the SO_DONTLINGER option in the Winsock setsockopt function.


IFWXSocket::Recv Method

Receives a buffer asynchronously; that is, performs an overlapped receive (or receive from operation, depending on the socket type).

HRESULT Recv(
  IFWXIOBuffer *pIOBuffer,
  IFWXIOCompletion *pIFWXIOCompletion,
  UserContextType UserData
);

Parameters

pIOBuffer
[in] Pointer to the buffer that receives the data.

This parameter may be set to NULL, in which case the Firewall service will create the buffer. In this case, the same buffer object can be passed between data filters, and buffer copy will be avoided. The IFWXIOCompletion::CompleteAsyncIO completion method receives a buffer object as one of its arguments.

pIFWXIOCompletion
[in] Pointer to the IFWXIOCompletion interface that receives the completion notification. This parameter is required; it cannot be NULL.
UserData
[in] An opaque value to pass to the IFWXIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification.


IFWXSocket::Send Method

Sends a buffer asynchronously; that is, performs an overlapped send operation.

HRESULT Send(
  IFWXIOBuffer *pIOBuffer,
  IFWXIOCompletion *pIFWXIOCompletion,
  UserContextType UserData
);

Parameters

pIOBuffer
[in] Pointer to the buffer to send.
pIFWXIOCompletion
[in] Pointer to the IFWXIOCompletion interface that is notified when the send operation is completed. Set this parameter to NULL if notification is not required.
UserData
[in] An opaque value to pass to the IFWXIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification, thereby allowing identification of each send operation.

Remarks

To receive a notification when the send operation is completed, specify an IFWXIOCompletion interface pointer in the pIFWXIOCompletion parameter.

See Also

IFWXIOBuffer


IFWXSocket::SendTo Method

Sends a buffer asynchronously on UDP sockets to a specific address; that is, performs an overlapped sendto operation.

HRESULT SendTo(
  IFWXIOBuffer *pIOBuffer,
  SOCKADDR *Address,
  INT AddressLength,
  IFWXIOCompletion *pIFWXIOCompletion,
  UserContextType UserData
);

Parameters

pIOBuffer
[in] Pointer to the buffer to send.
Address
[in] When calling this method on an external socket, this sockaddr structure should contain the target address for a UDP datagram. When calling this method on an internal socket, this parameter should contain the address of the datagram source. This is typically the Internet address from which the pIOBuffer packet originated. That is, the internal socket is associated with the Internet address of the pIOBuffer packet.
AddressLength
[in] Length, in bytes, of the Address parameter.
pIFWXIOCompletion
[in] Pointer to an IFWXIOCompletion interface that is notified when the send operation is completed. Set this parameter to NULL if notification is not required.
UserData
[in] An opaque value to pass to the IFWXIOCompletion::CompleteAsyncIO notification method. This parameter provides a context to the notification.

Remarks

To receive a notification when the sendto operation is completed, specify a IFWXIOCompletion interface pointer in the pIFWXIOCompletion parameter.


IFWXSocket::Shutdown Method

Starts transport shutdown on this socket.

HRESULT Shutdown(
  BOOLEAN fAbortive
);

Parameters

fAbortive
[in] Close-type flag. If TRUE, the connection will be hard-closed (RST packet). If FALSE, it will be closed gracefully (FIN packet).

Remarks

Shutdown is done with how=SD_SEND. An abortive shutdown is carried out by setting the SO_DONTLINGER option in the Winsock setsockopt function.


IFWXUdpDestination

The IFWXUdpDestination interface controls the outcome of a UDP destination event. Use IFWXUdpDestination::Deny to block the destination. Call IFWXUdpDestination::SetProtocol to associate the destination with the given protocol and perform access control based on the user's permission to access the protocol.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IFWXUdpDestination Methods | Description
SetProtocol | Associates the destination with a given protocol.
Deny | Blocks the destination.

SetProtocol and Deny are like the corresponding methods of IFWXConnection, but the DWORD parameter of SetProtocol is currently reserved.

Implementation

This interface is implemented by the Firewall service.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


IFWXUdpDestination::Deny Method

Blocks the destination.

HRESULT Deny(
  DWORD Reserved
);

Parameters

Reserved
[in] Reserved for future use. Must be zero.

Return Values

S_OK
The destination will be denied.
E_INVALIDARG
Invalid (non-zero) value was passed to the Reserved parameter.
FWX_E_BAD_CONTEXT
The method was not called in the context of an event handler.


IFWXUdpDestination::SetProtocol Method

Associates the UDP destination with a given protocol and performs access control based on the user's permission to access the protocol.

HRESULT SetProtocol(
  REFGUID ProtocolGuid,
  DWORD dwFlags
);

Parameters

ProtocolGuid
[in] GUID of the protocol to attempt to associate with the destination.
dwFlags
[in] This flag parameter can be a combination of the following values:
Value | Description
0 | "Send" is allowed for the destination.
FWX_FLAG_BIDIRECTIONAL | "Send-Receive" is allowed for the destination.

Return Values

S_OK
The method succeeded.
E_INVALIDARG
Invalid (non-zero) value was passed to the Reserved parameter.
FWX_E_BAD_CONTEXT
The method was not called in the context of an event handler.
FWX_E_PROTOCOL_RULES_DENIED
The protocol rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.


Structures

The application filter API uses the following unions and structures:

  • FwxAcceptEvent
  • FwxBindEvent
  • FwxConnectEvent
  • FwxEndConnectionEvent
  • FwxFilterHookEvents
  • FwxGetHostByAddrEvent
  • FwxGetHostByNameEvent
  • FwxListenEvent
  • FwxPortRangeEvents
  • FwxFirewallEvent
  • FwxFirewallEventParameters
  • FwxUdpDestination


FwxAcceptEvent

The FwxAcceptEvent structure contains parameters for the fwx_AcceptedConnection event.

This event is a notification on a new connection that arrived on a listening socket.

typedef struct {
  LPSOCKADDR RemoteAddress;
  DWORD RemoteAddressLength;
  LPSOCKADDR LocalAddress;
  DWORD LocalAddressLength;
  IFWXConnection * piConnectionAccepted;
  FwxFilterAccess FilterAccess;
} FwxAcceptEvent;

Members

RemoteAddress
[in] Pointer to a sockaddr structure that contains the address of the connecting peer.
RemoteAddressLength
[in] Size, in bytes, of the RemoteAddress member.
LocalAddress
[in] Pointer to a sockaddr structure that contains the local address for this connection.
LocalAddressLength
[in] Size, in bytes, of the LocalAddress member.
piConnectionAccepted
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for the newly accepted connection.
FilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny.

Remarks

The listening socket was created as a result of a Firewall client call to the bind and listen APIs, or as a result of a filter successfully calling IFWXSession::BindForClient.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxBindEvent, FwxListenEvent


FwxBindEvent

The FwxBindEvent structure contains parameters for the fwx_Bind_Udp and fwx_Bind_Tcp events.

These events are the result of Firewall client calling the bind function, or an application filter calling the IFWXSession::BindForClient method.

typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection * piConnection;
  FwxFilterAccess FilterAccess;
  GUID ProtocolGuid
} FwxBindEvent;

Members

Address
[in] Pointer to a sockaddr structure that contains the address that the client wants to assign to the socket.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.
FilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumeration. This member indicates the current access status. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny.
ProtocolGuid
[in] The globally unique identifier (GUID) for the protocol, if known to the Firewall service. If the protocol is not known, this parameter has the value GUID_NULL.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxConnectEvent

The FwxConnectEvent structure contains parameters for the fwx_Connect_Tcp event.

This information concerns a connect call made by a Firewall client, or a TCP connection initiated by a SecureNAT client.

typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection * piConnection;
  FwxFilterAccess FilterAccess;
} FwxConnectEvent;

Members

Address
[in] Pointer to a sockaddr structure that contains the address to which the client is attempting to connect.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.
FilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny.

Remarks

SecureNAT connections will generate an event only if the connection is to a port that is a primary port of a predefined protocol (including protocols defined by IFWXFilterAdmin::RegisterProtocolForFilter) or to an address specified in a call to IFWXSession::AllowFutureConnect. Other connection attempts are dropped by the system before they reach the Firewall service. For more information about NAT and SecureNAT, see Secure Network Address Translation.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxFirewallEventParameters, FwxFirewallEventType


FwxEndConnectionEvent

The FwxEndConnectionEvent structure contains parameters for the fwx_ConnectionTerminating event.

This event occurs as a result of a connection being terminated. A filter that holds a reference to the Firewall service connection object must release the reference so that the connection object can be deleted.

typedef struct {
  IFWXConnection * piConnection;
} FwxEndConnectionEvent;

Members

piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object that is terminating. References to this object must be released in response to the event.

Remarks

It is unnecessary to register for this event in the IFWXFilter::FilterInit method because a session filter is never attached in response to this event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxEstablishedConnectionEvent

The FwxEstablishedConnectionEvent structure contains parameters for the fwx_EstablishedConnection event.

This event provides notification of connections established for IFWXSession::AllowFutureConnect, IFWXSession::BindForClient, and IFWXSession::RedirectConnections methods. When a connection is made as a result of a call to one of these three methods, the Firewall service creates this event.

Remarks

It is impossible to register for this event. This event is sent only to the filter that called one of the previous methods and passed its interface.

typedef struct{
  INT Protocol;
  [ref] LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection *piConnection;
  UserContextType UserContext;
} FwxEstablishedConnectionEvent;

Members

Protocol
[in] Protocol flags. This parameter can have the following flag values:
Value | Description
FWX_PROTOCOL_TCP | The connection will use the TCP protocol.
FWX_PROTOCOL_UDP | The connection will use the UDP protocol.

Address
[in] Pointer to a sockaddr structure that contains the address to which the client is attempting to connect.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object that is terminating. References to this object must be released in response to the event.
UserContext
[in] User context for the connection. This is identical to the UserContextType parameter of the function that created the connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxFilterHookEvents

The FwxFilterHookEvents structure defines all the events that a filter wants to monitor. When a user session generates an event that the filter monitors, a session-filter object is created and notified of the event. At this point, the session filter may change the set of events for that specific client session.

typedef struct {
  DWORD dwGlobalEvents;
  DWORD dwNumPortRanges;
  PortRangeEvents * PortRangeEvents;
} FwxFilterHookEvents;

Members

dwGlobalEvents
A combination of FwxFirewallEventType values combined with a combination of FwxFirewallEventSource values by using the bitwise OR operator.

Specifies events for notification on all ports or events that are not associated with port numbers (name resolution).

dwNumPortRanges
Number of entries in the array specified by the PortRangeEvents member.
PortRangeEvents
Pointer to an array of FwxPortRangeEvents structures.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXFilter::AttachToSession, IFWXFilter::FilterInit, IFWXFirewall::DuplicateFilterHookEvents


FwxGetHostByAddrEvent

The FwxGetHostByAddrEvent structure contains parameters for the fwx_GetHostByAddr event.

This event is a notification on an Firewall client operation that uses the Winsock gethostbyaddr function. It allows the filter to modify or block a request that uses gethostbyaddr by using the IFWXGetXByY::SetResult or IFWXGetXByY::Deny method. Two events are generated, one before and one after the actual name resolution.

typedef struct {
  BYTE * Address;
  DWORD AddressLength;
  INT AddressType;
  LPHOSTENT Hostent;
  DWORD HostentLength;
  BOOL fBeforeAction;
  FwxFilterAccess FilterAccess;
  IFWXGetXByY * piGetXByY;
} FwxGetHostByAddrEvent;

Members

Address
[in] Address being looked up in network byte order.
AddressLength
[in] Size in bytes of the buffer pointed to by the Address member.
AddressType
[in] Type of address, such as the AF_INET address family type (defined as TCP, UDP, and other associated Internet protocols). Address family types and their corresponding values are defined in winsock2.h.
Hostent
[in] Pointer to a buffer containing the response hostent structure. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE. Otherwise, the value of the Hostent member is undefined.
HostentLength
[in] Size, in bytes, of the buffer pointed to by the Hostent member.
fBeforeAction
Before-action flag. The value of this flag is TRUE when called before name resolution is done.

It is FALSE when the gethostbyaddr function is called after name resolution is done. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE.

FilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may call the IFWXGetXByY::Deny method to modify the access status.
piGetXByY
[in] Pointer to a IFWXGetXByY interface that can be used to control the outcome of the name query.

Remarks

This event is generated only for Firewall clients (fwxSourceWSP); it is not generated for SecureNAT clients.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXGetXByY


FwxGetHostByNameEvent

The FwxGetHostByNameEvent structure contains parameters for the fwx_GetHostByName event.

This event is a notification on a gethostbyname operation performed by a Firewall client. It allows the filter to modify or block a gethostbyname request. Two events are generated, one before and one after actual name resolution.

typedef struct {
  LPSTR Hostname;
  LPHOSTENT Hostent;
  DWORD HostentLength;
  BOOL fBeforeAction;
  FwxFilterAccess FilterAccess;
  IFWXGetXByY * piGetXByY;
} FwxGetHostByNameEvent;

Members

Hostname
[in] Pointer to the host name being looked up.
Hostent
[in, out] Pointer to a buffer for setting the response hostent structure. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE.
HostentLength
[in] Size, in bytes, of the buffer pointed to by the Hostent member.
fBeforeAction
Before-action flag. It is TRUE when called before name resolution is done.

It is FALSE when this gethostbyname is called after name resolution is done. The buffer contains a valid hostent structure if the fBeforeAction member is FALSE.

FilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. This member indicates the current access status. The filter may call the IFWXGetXByY::Deny method to modify the access status.
piGetXByY
[in] Pointer to a IFWXGetXByY interface that can be used to control the outcome of the name query.

Remarks

This event is generated only for Firewall clients (fwxSourceWSP), not for SecureNAT clients.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXGetXByY


FwxListenEvent

The FwxListenEvent structure contains parameters for the fwx_Listen event.

This is the result of the Firewall client calling the listen function, or an application filter calling the IFWXSession::BindForClient method.

typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection * piConnection;
} FwxListenEvent;

Members

Address
[in] Pointer to a sockaddr structure that contains the address the socket was assigned. This is the same as the result of calling the getsockname function on the socket.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.

Remarks

There is no way for a filter to fail this request because client applications do not expect the listen function to fail. The place for a filter to deny inbound access is in the bind request or when a connection actually arrives. For example, in the fwx_AcceptedConnection event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxPortRangeEvents

The FwxPortRangeEvents structure defines a set of events for a port range.

typedef struct {
  USHORT StartPort;
  USHORT EndPort;
  DWORD dwSocketEvents;
} FwxPortRangeEvents;

Members

StartPort
First port in the range.
EndPort
Last port in the range.
dwSocketEvents
FwxFirewallEventType values combined with FwxFirewallEventSource values by using the bitwise OR operator.

Remarks

The following events do not have a port associated with them and should not be specified with FwxPortRangeEvents: fwx_ConnectionTerminating fwx_GetHostByName fwx_GetHostByAddr.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxFilterHookEvents


FwxFirewallEvent

The FwxFirewallEvent structure describes a firewall event.

typedef struct {
  FwxFirewallEventType EventType;
  FwxFirewallEventSource EventSource;
  FwxFirewallEventParameters Parameters;
} FwxFirewallEvent;

Members

EventType
Type of event. This member is a value from the FwxFirewallEventType enumerated type.
EventSource
Source of the event. This member is a value from the FwxFirewallEventSource enumerated type.
Parameters
Parameters specific to the firewall event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxFirewallEventParameters

The FwxFirewallEventParameters structure is a union of event-specific parameters.

typedef union{
  FwxConnectEvent       Connect;
  FwxUdpDestination     UdpDest;
  FwxBindEvent          Bind;
  FwxListenEvent        Listen;
  FwxAcceptEvent        Accept;
  FwxGetHostByAddrEvent GetHostByAddr;
  FwxGetHostByNameEvent GetHostByName;
  FwxEndConnectionEvent EndConnect;
  FwxEstablishedConnectionEvent EstablishedConnection;
} FwxFirewallEventParameters;

Members

Connect
Parameters for an fwx_Connect_Tcp event. For more information, see FwxConnectEvent.
UdpDest
UdpDest parameters for a fwx_Udp_Destination event. For more information, see FwxUdpDestination.
Bind
Parameters for fwx_Bind_Tcp, and fwx_Bind_Udp events. For more information, see FwxBindEvent.
Listen
Parameters for an fwx_Listen event. For more information, see FwxListenEvent.
Accept
Parameters for an fwx_AcceptedConnection event. For more information, see FwxAcceptEvent.
GetHostByAddr
Parameters for an fwx_GetHostByAddr event. For more information, see FwxGetHostByAddrEvent.
GetHostByName
Parameters for an fwx_GetHostByName event. For more information, see FwxGetHostByNameEvent.
EndConnect
Parameters for an fwx_ConnectionTerminating event. For more information, see FwxEndConnectionEvent.
EstablishedConnection
Parameters for an fwx_EstablishedConnection event. For more information, see FwxEstablishedConnectionEvent.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


FwxUdpDestination

The FwxUdpDestination structure contains parameters for the fwx_Udp_Destination event.

This event is generated when a UDP destination is generated, which occurs under the following circumstances:

  • A Firewall client application calls the connect function on a remote UDP socket.
  • A firewall client (either SecureNAT or Firewall service) attempts a sendto operation to a new destination.
  • A packet has just been sent to the client from the given address.
typedef struct {
  LPSOCKADDR Address;
  DWORD AddressLength;
  IFWXConnection *piConnection;
  IFWXUdpDestination    *piUdpDestination;
  FwxFilterAccess FilterAccess;
} FwxUdpDestination;

Members

Address
[in] Pointer to a sockaddr structure that contains the address to which the client is attempting to connect.
AddressLength
[in] Length, in bytes, of the data pointed to by the Address member.
piConnection
[in] Pointer to the IFWXConnection interface on the Firewall service connection object for this request.
piUdpDestination
[in] Pointer to the IFWXUdpDestination interface.
FilterAccess
[in] Access status for the event. This is a value from the FwxFilterAccess enumerated type. On input, this member indicates the current access status. The filter may not modify this member.

Remarks

The Firewall service keeps a cache of known UDP sources and destinations for each UDP connection object. An event is only generated for destinations that are not in this cache.

The FilterAccess member for the event pertains only to outgoing packets to the destination. The filter may not directly modify this member. To modify the access status, a filter may call IFWXConnection::SetProtocol or IFWXConnection::Deny. Data filters installed by a handler for this event are associated with the destination, and may be detached by the Firewall service when it is invalidating a cached destination.

Although an fwx_Udp_Destination event may be generated as a result of an incoming datagram; it is not intended for interception of inbound traffic. To examine inbound datagrams, use the fwx_Bind_Udp event.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


Filter Enumerated Types

The application filter API uses the following enumerated types.

  • FwxFilterAccess
  • FwxDataFilterPriorityClass
  • FwxFirewallEventSource
  • FwxFirewallEventType
  • FwxScope


FwxFilterAccess

The FwxFilterAccess enumerated type contains values that indicate the type of access permission for a filter event.

enum FwxFilterAccess {
  FWX_ALLOW,
  FWX_DENY,
  FWX_PASS,
  FWX_EMULATE
};

Elements

FWX_ALLOW
Grants permission. Overrides the default (built in) protocol/permission check.
FWX_DENY
Denies the action.
FWX_PASS
Allows access if none of the other filters (including the built-in rules) denies it and at least one filter (including the built-in) allows it. This is the default value for FwxFilterAccess.
FWX_EMULATE
Signals that the filter wants to intercept and implement the request, emulating an external connection.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxGetHostByNameEvent, FwxGetHostByAddrEvent, FwxUdpDestination, FwxAcceptEvent, FwxBindEvent, FwxConnectEvent


FwxDataFilterPriorityClass

The FwxDataFilterPriorityClass enumerated type contains values used to specify the order of data filters for the same connection. Within the same priority class, the order will be arbitrary.

enum FwxDataFilterPriorityClass {
  fwx_dfpc_NAT,
  fwx_dfpc_Internal,
  fwx_dfpc_PostTrust,
  fwx_dfpc_Middle,
  fwx_dfpc_PreTrust,
  fwx_dfpc_External,
  fwx_dfpc_Emulation
};

Elements

fwx_dfpc_NAT
As close to the client as possible. This should be used only if the data filter is a SecureNAT editor.
fwx_dfpc_Internal
As close to the client as possible for a non-SecureNAT filter.
fwx_dfpc_PostTrust
Close to the client side.
fwx_dfpc_Middle
Middle of the chain. Virus scanners should use this priority.
fwx_dfpc_PreTrust
Close to the server side.
fwx_dfpc_External
As close to the external source as possible.
fwx_dfpc_Emulation
Used by emulation filters. The filter is the source of the data.

Remarks

Each priority setting is defined as being closer to the client or closer to the server. A data filter that is closer to the client is likely to be the first to examine data flowing from the client, and unlikely to be the first to examine data flowing to the client. A data filter that is closer to the server is likely to be the first to examine data flowing from the server to the client, and unlikely to be the first to examine data flowing from the client to the server.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXConnection::AttachDataFilter, IFWXConnection::AttachDataFilterWithDestination, IFWXConnection::EmulateConnection, IFWXSession::SetDataFilterFactory


FwxFirewallEventSource

The FwxFirewallEventSource enumerated type contains values that indicate the source of an event. The source can be either a SecureNAT client or a Firewall client.

enum FwxFirewallEventSource {
  fwxSourceWSP,
  fwxSourceNAT
};

Elements

fwxSourceWSP
Source is a Firewall client.
fwxSourceNAT
Source is NAT.

Remarks

Use the fwxSourceNAT macro to set both the fwxSourceWSP and fwxSourceWSP values. For more information on developing filters for SecureNAT and Firewall clients, see Filter Requirements for SecureNAT Clients and Filter Requirements for Firewall Clients.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

FwxFilterHookEvents, FwxPortRangeEvents, FwxFirewallEvent, FwxGetHostByNameEvent


FwxFirewallEventType

The FwxFirewallEventType enumerated type defines the types of events to which a filter may hook. Each value in this enumeration is a bit. Values can be combined by using the bitwise OR operator to specify a set of events.

enum FwxFirewallEventType {
  fwx_Connect_Tcp,
  fwx_Udp_Destination,
  fwx_Bind_Tcp,
  fwx_Bind_Udp,
  fwx_Listen,
  fwx_AcceptedConnection,
  fwx_GetHostByName,
  fwx_GetHostByAddr,
  fwx_ConnectionTerminating
  fwx_EstablishedConnection
};

Elements

fwx_Connect_Tcp
Connect request for TCP sockets. For more information, see FwxConnectEvent.
fwx_Udp_Destination
Connect request for UDP sockets. For more information, see FwxUdpDestination.
fwx_Bind_Tcp
Bind request for TCP sockets. For more information, see FwxBindEvent.
fwx_Bind_Udp
Bind request for UDP sockets. For more information, see FwxBindEvent.
fwx_Listen
Listen on a TCP socket. For more information, see FwxListenEvent.
fwx_AcceptedConnection
Actual inbound connection on a listening TCP socket. For more information, see FwxAcceptEvent.
fwx_GetHostByName
The Firewall client calls the gethostbyname function. This event can be generated only by a Firewall client. It will not be generated for a SecureNAT client. For more information, see FwxGetHostByNameEvent.
fwx_GetHostByAddr
The Firewall client calls the gethostbyaddr function. This event can be generated only by a Firewall client. It will not be generated for a SecureNAT client. For more information, see FwxGetHostByAddrEvent.
fwx_ConnectionTerminating
Notification before shutting down a connection object. For more information, see FwxEndConnectionEvent.
fwx_EstablishedConnection
Notification for connections established for IFWXSession::AllowFutureConnect, IFWXSession::BindForClient, and IFWXSession::RedirectConnections methods. This event is created by the Firewall service. For more information, see FwxEstablishedConnectionEvent.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.

See Also

IFWXConnection, IFWXSession::SetDataFilterFactory


FwxScope

The FwxScope enumerated type defines the scope of application filter installation actions.

enum FwxScope {
  fwx_DefaultScope,
  fwx_ArrayScope,
  fwx_EnterpriseScope
};

Elements

fwx_DefaultScope
Used by get operations to retrieve the object that is appropriate for the current configuration. This may be either an array or enterprise scope, depending on the type of policy that applies to the array.
fwx_ArrayScope
Array-level scope applies.
fwx_EnterpriseScope
Enterprise-level scope applies.

Requirements

Windows NT/2000: Requires Windows 2000.
Version: Requires ISA Server 2000.
Header: Wspfwext.idl.


Web Filter Reference

The Web Filter (ISAPI) Reference section contains the following topics:

  • Filter Entry Points
  • Notification Structures
  • Event Notifications


Filter Entry Points

Web (ISAPI) filters for the ISA Web proxy service implement the following standard entry points:

  • GetFilterVersion
  • HttpFilterProc
  • TerminateFilter


GetFilterVersion

The GetFilterVersion function is the first entry-point function called by the ISA Web proxy service on your Web (ISAPI) filter and must be present for the filter to work properly. Its declaration is:

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 with which the filter can indicate filter version number, notifications, and priority desired. There is also a space for the filter application to provide a descriptive text.

Return Values

If this function returns TRUE, the filter will remain loaded. If the function returns FALSE, the filter will not receive any event notifications.

Note It is important to register only for those notifications that are necessary for your filter's purposes. Registering for additional notifications will reduce performance.


HttpFilterProc

Whenever a notification event for which the filter has registered (in GetFilterVersion) occurs, the ISA Web proxy service calls HttpFilterProc. The Web proxy service uses this function to pass information and control to the Web (ISAPI) filter. The declaration of HttpFilterProc is:

DWORD WINAPI HttpFilterProc(
  PHTTP_FILTER_CONTEXT pfc,
  DWORD notificationType,
  LPVOID pvNotification
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
notificationType
Points to a bitmask that indicates the type of notification event that is being processed. See Event Notifications for a list of event-notification types.
pvNotification
The notification-specific structure that contains more information about the current context of the request.
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
SF_NOTIFY_AUTH_COMPLETE | HTTP_FILTER_AUTH_COMPLETE_INFO

Note SF_NOTIFY_SEND_RESPONSE is not used when the ISA Web proxy service sends a response. However, it is called when a filter generates a response itself by using ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADERS).

Return Values

Returns one of the following values that indicate how the application handled the event.

SF_STATUS_REQ_FINISHED
The filter has handled the HTTP request. The server should disconnect the session.
SF_STATUS_REQ_FINISHED_KEEP_CONN
Treated the same as SF_STATUS_REQ_FINISHED. After this notification is received, the connection is closed.
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 value indicates that the full request has not yet been received; the Web server should issue another read and notify the filter with the additional data read.

Remarks

This function usually serves as the dispatch for a Web (ISAPI) filter. Separate functions are often created to serve as handlers for the separate notifications, especially if the handling code is complicated.


TerminateFilter

This function indicates to the filter that it is going to be removed from memory. When this function is called, you should make sure that the filter closes any attachments it has made to system resources.

The TerminateFilter function is declared as:

BOOL WINAPI TerminateFilter(
  DWORD dwFlags
);

Parameters

dwFlags
No values for dwFlags have been identified at this time.


Notification Structures

The following structures are used by Web (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_SEND_RESPONSE
  • HTTP_FILTER_URL_MAP
  • HTTP_FILTER_VERSION

All function declarations and data structures are available in the Web (ISAPI) filter header file httpfilt.h in the Windows 2000 SDK.


HTTP_FILTER_ACCESS_DENIED

The ISA Web proxy service 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;
  const CHAR * pszPhysicalPath;
  DWORD dwReason;
} HTTP_FILTER_ACCESS_DENIED, *PHTTP_FILTER_ACCESS_DENIED;

Members

pszURL
Points to a null-terminated string that specifies the URL that requested access to the resource.
pszPhysicalPath
The physical path of the resource that was requested.
dwReason
A DWORD date type containing flags that indicate the reasons for the denial. Can have one of the following values.
Value | Meaning
SF_DENIED_LOGON | The client could not be logged on.
SF_DENIED_RESOURCE | The resource was denied by a Windows discretionary access control list (DACL).
SF_DENIED_FILTER | A Web (ISAPI) filter denied the request.
SF_DENIED_APPLICATION | An ISAPI extension 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 access to the requested resource has been denied by the server. The structure is generated when there has been a logon failure, or when a user requests a resource that has an associated DACL 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_AUTH_COMPLETE_INFO

This notification allows you to view or modify the method, URL, version, or headers sent from the client. This notification fires after the client's identity has been negotiated with the client. Because of the timing of this notification, the AUTH_USER server variable can be used to reliably obtain the identity of the user. Also, functionality is provided to retrieve a copy of the token that ISA will impersonate when processing the request.

If your filter should be notified for this event, it should register for the SF_NOTIFY_AUTH_COMPLETE event.

typedef struct _HTTP_FILTER_AUTH_COMPLETE_INFO
{
  BOOL (WINAPI * GetHeader);
  BOOL (WINAPI * SetHeader);
  BOOL (WINAPI * AddHeader);
  BOOL (WINAPI * GetUserToken);
  DWORD HttpStatus;
  BOOL  fResetAuth;
  DWORD dwReserved;
} HTTP_FILTER_AUTH_COMPLETE_INFO, *PHTTP_FILTER_AUTH_COMPLETE_INFO;

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 must not include the trailing colon.
SetHeader
Points to the SetHeader function, which changes or deletes the value of a header. The function can not 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.
GetUserToken
Returns handle to Token of user for whom impersonation will be performed.
fResetAuth
If set to TRUE, the authentication process will be reset, and no impersonation will be done.
HttpStatus
Not used.
dwReserved
A DWORD reserved for later use.

Remarks

The SF_NOTIFY_AUTH_COMPLETE notification should be called before you use BASIC Authentication, as in the case when you want to map a user to a Windows 2000 user.

Other authentication schemes, such as NTLM, KERBEROS, INTEGRATED, and NEGOTIATE, will not lead to a SF_NOTIFY_AUTH_COMPLETE notification.

All authentication schemes processes should result in either SF_NOTIFY_AUTH_COMPLETE, authentication, giving the filter a handle to a token of the user to be impersonated, or ACCESS_DENIED, when the user is not recognized by the system.

SF_NOTIFY_AUTH_COMPLETE notification may be used for:

  • Accessing the user token of the user to be impersonated.
  • All actions that can be done in PREPROC_HEADERS, such as SET/GET/ADD request headers, including the URL special header, allowing the filter to remap the requested URL to a different URL.
  • Resetting authentication.

Here is an example of how to use the GetUserToken function to get the impersonated user name and domain.

PHTTP_FILTER_AUTH_COMPLETE_INFO pAuthCompInfo =(PHTTP_FILTER_AUTH_COMPLETE_INFO) pvNotification;

HANDLE TokenHandle;
DWORD dwLen = 0;
PTOKEN_USER pTokenUser = NULL;

// Get user token.
if ( pAuthCompInfo->GetUserToken(pFC,&TokenHandle) )
{
            // Get token information size.
    if ( !GetTokenInformation(TokenHandle,TokenUser,NULL,dwLen,&dwLen) )
        {
                    dwErr = GetLastError();
            if ( ERROR_INSUFFICIENT_BUFFER == dwErr )
            {
                                   // Alocate buffer for token information.
            pTokenUser = (PTOKEN_USER)GlobalAlloc(GPTR,dwLen);
                dwErr = S_OK;
            }
        }

                       // Now get the actual token information.
        if ( dwErr != S_OK ||
 !GetTokenInformation(TokenHandle, TokenUser,pTokenUser,dwLen,&dwLen) )
        {
            // Error …
        }
        else // We have the token information in hand.
        {
                                   // Extract from the token information - the SID.
            SID *pSid = (SID *)pTokenUser->User.Sid;
            char name[MAX_NAME], domain[MAX_NAME];
            DWORD dwNLen = MAX_NAME, dwDLen = MAX_NAME;
            SID_NAME_USE eUse;

                                     // Get  the user name and the domain from the SID.
            if ( ! LookupAccountSid(NULL,pSid,name,&dwNLen,domain,&dwDLen,&eUse) )
            {
                // Error …
            }
            else
            {
                                                // name buffer contains user name.
                                                // domain buffer contains user domain.
            }
        }
    }


HTTP_FILTER_AUTHENT

The ISA Web proxy service 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
Points to a string containing the user name for this request. An empty string indicates an anonymous user.
cbUserBuff
The size of the buffer pointed to by pszUser. This is guaranteed to be at least SF_MAX_USERNAME.
pszPassword
Points to a string containing the password for this request.
cbPasswordBuff
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. The pszUser and pszPassword members contain the information sent by the client. After exiting this function, these values must represent a valid Windows user account and password. ISA Web proxy will then impersonate this account to gain access to resources. If the authentication method used is integrated Windows authentication, the password value will not be available.


HTTP_FILTER_CONTEXT

This structure is used by HttpFilterProc to obtain information about the current request.

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
The size of this structure, in bytes.
Revision
The revision level of this structure. This is less than or equal to the version of the document HTTP_FILTER_REVISION.
ServerContext
Reserved for server use.
ulReserved
Reserved for server use.
fIsSecurePort
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
Pointer 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
Pointer to a function that retrieves information about the server and this connection. For some notifications, some variables may not be defined. For example, notifications which occur before PREPROC_HEADERS, such as the READ_RAW_DATA notification, may not be defined.
AddResponseHeaders
Pointer to the AddResponseHeaders function that adds a header to the HTTP response.
WriteClient
Pointer to the WriteClient function that sends raw data back to the client.
AllocMem
Pointer to the AllocMem function used to allocate memory. Any memory allocated with this function will automatically be freed when the session ends.
ServerSupportFunction
Pointer to the ServerSupportFunction function used to extend the Web (ISAPI) filter functions. Parameters are specific to the extensions.


AddResponseHeaders

Points to the AddResponseHeaders function that adds a header to the HTTP response.

The AddResponseHeaders function is declared as:

BOOL WINAPI * AddResponseHeaders(
  PHTTP_FILTER_CONTEXT pfc,
  LPSTR lpszHeaders,
  LPSTR dwReserved
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
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 clients 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 can do so by using the AddHeader member of the HTTP_FILTER_SEND_RESPONSE structure.


AllocMem

Points to the AllocMem function that is used to allocate memory. Any memory allocated by using this function will automatically be freed when the session ends.

The AllocMem callback function allocates memory from the process heap to a buffer. Any memory allocated with this function will automatically be freed by the ISA Web proxy service when the session ends.

The AllocMem function is declared as:

VOID * WINAPI * AllocMem(
  PHTTP_FILTER_CONTEXT pfc,
  DWORD cbSize,
  DWORD dwReserved
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current active HTTP transaction.
cbSize
Indicates the size of the buffer to be allocated, in bytes.
dwReserved
Reserved for use by the server.


GetServerVariable

Pointer to a function that retrieves information about the server and this connection. For some notifications, some variables might not be defined. For example, notifications that occur before PREPROC_HEADERS, such as the READ_RAW_DATA notification, may not be defined.

Some server variables, such as Request_Method and Content_Length are embedded in the EXTENSION_CONTROL_BLOCK structure. You can use GetServerVariable to obtain information about the request or server that is not included in the EXTENSION_CONTROL_BLOCK.

The declaration of GetServerVariable is:

BOOL WINAPI GetServerVariable(
  HCONN hConn,
  LPSTR lpszVariableName,
  LPVOID lpvBuffer,
  LPDWORD lpdwSizeofBuffer
);

Parameters

hConn
Specifies the connection handle.
lpszVariableName
A null-terminated string that indicates which variable is requested. The following table lists the possible variables. Variables supported by IIS, but not by ISA, are presented in this table, along with information on how the ISA Web proxy service responds to the variable.
Variable | Description
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 raw form. The header names and values appear as they are sent by the client. Currently, this value is primarily used by proxy servers and similar applications.
APPL_MD_PATH | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
APPL_PHYSICAL_PATH | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
AUTH_PASSWORD | Specifies the value entered in the client's authentication dialog box. 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, Secure Sockets Layer (SSL) or Private Communication Technology (PCT), basic, and integrated Windows authentication.
AUTH_USER | Specifies the value entered in the client's authentication dialog box.
CERT_COOKIE | Specifies a unique identifier (ID) for a client certificate. Returned as a string. Can be used as a signature for the entire client certificate.
CERT_FLAGS | If bit0 is set to 1, a client certificate is present. If bit1 is set to 1, the certification authority (CA) of the client certificate is invalid; that is, it is not on this server's list of recognized CAs.
CERT_ISSUER | Specifies the issuer field of the client certificate. For example, the codes might be O=MS, OU=IAS, CN=user name, C=USA, and so on.
CERT_KEYSIZE | Specifies the number of bits in the 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 that 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 request for a power-on self test (POST).
LOGON_USER | The Windows account that the user is logged into.
HTTPS | Returns On if the request came in through a secure channel (with SSL encryption), or Off if the request is for an unsecure 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 | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
INSTANCE_META_PATH | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
PATH_INFO | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
PATH_TRANSLATED | Not supported in ISA; will always return the error (ERROR_INVALID_INDEX).
QUERY_STRING | Not supported in ISA; will always return an empty string.
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 if reverse Domain Name System (DNS) is enabled. Otherwise, this value is set to the IP address specified by REMOTE_ADDR.
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 | Not supported in ISA; will always return "w3proxy.dll".
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 | Returns "Microsoft-ISA/3.0".
URL | Will return the request URL (after the request has been parsed). HTTP_Proxy_URL will also return this value.

lpvBuffer
Points to the buffer to receive the requested information.
lpdwSizeofBuffer
Points to a DWORD data type 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.

ERROR_INVALID_PARAMETER
Bad connection handle or invalid values 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.


ServerSupportFunction

Points to the ServerSupportFunction function used to extend the Web (ISAPI) filter functions. Parameters are specific to the extensions. The ServerSupportFunction callback function can be used by Web (ISAPI) filters to accomplish a wide variety of tasks.

The ServerSupportFunction function is declared as:

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE sfReq,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

The parameter sfReq specifies the particular support function that is to be executed by the ISA Web proxy service. The remaining parameters are described in the individual support function sections; see the following list:

SF_REQ_ADD_HEADERS_ON_DENIAL

SF_REQ_DISABLE_NOTIFICATIONS

SF_REQ_NORMALIZE_URL

SF_REQ_SEND_RESPONSE_HEADER

SF_REQ_SET_NEXT_READ_SIZE

Note If a parameter is designated as unused for a particular support function, you should set the parameter to NULL or 0, as appropriate.

SF_REQ_GET_CONNID is not supported by ISA or by IIS 4.0 or later and will return 0.

SF_REQ_GET_PROPERTY is not supported by ISA and will return 0.

SF_REQ_SET_PROXY_INFO is not used in the ISA implementation of ISAPI.


SF_REQ_ADD_HEADERS_ON_DENIAL

This support function allows your Web (ISAPI) filter to add specified headers to the server error response, in the event that the HTTP request is denied by the server. This allows an authentication filter to advertise its services without filtering every request.

Note This support function will not work properly if called during the processing of a SF_NOTIFY_SEND_RAW_DATA notification.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_ADD_HEADERS_ON_DENIAL,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
pData
Null-terminated string pointing to one or more HTTP header lines. Each individual header should be terminated with a carriage return and linefeed.
ul1
Unused in this support function.
ul2
Unused in this support function.

Remarks

Generally, the HTTP headers should be WWW-Authenticate headers that specify custom authentication schemes. However, no restriction is placed on which headers can be specified. The ISA Web proxy service will advertise both Basic and integrated Windows authentication, individually and collectively, if those authentication schemes are enabled.


SF_REQ_DISABLE_NOTIFICATIONS

This support function can be used to disable specific notification types for your Web (ISAPI) filter for the remaining lifetime of that request. If a particular notification event is disabled for your filter, the ISA Web server will not call your filter when that notification event occurs.

New requests will generate the notifications for which your filter registered when it was loaded.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_DISABLE_NOTIFICATIONS,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
pData
Unused in this support function.
ul1
Contains flags, described in HTTP_FILTER_VERSION, that indicate which notification types are to be disabled.
ul2
Unused in this support function.


SF_REQ_NORMALIZE_URL

This support function can be used to normalize the URL. Normalization includes decoding hex codes, removing illegal characters, and some internationalization conversions.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_NORMALIZE_URL,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
pData
Points to the URL string to normalize.
ul1
Unused in this support function.
ul2
Unused in this support function.


SF_REQ_SEND_RESPONSE_HEADER

You can use this support function to ask the ISA Web proxy service to send a complete HTTP response header to the client browser, including the HTTP status, server version, message time, and MIME version. Your filter can also, optionally, append other header information to the end of a header generated by the ISA Web proxy service, such as a Content-Type or Content-Length header.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_SEND_RESPONSE_HEADER,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current active HTTP transaction.
pData
Points to a null-terminated string that contains an HTTP status string, such as "401 Access Denied." If pData is set to NULL, then the default response, "200 OK," will be sent in the response header.
ul1
Points to a null-terminated string that contains the optional HTTP headers that you want to be appended to the response header.
ul2
Unused in this support function.

Note If you append your own headers to the server-generated headers, you must terminate the header string with an extra carriage return and linefeed.

This support function can be called only once for each HTTP request.

Remarks

An ISAPI Filter may cause a recursive call of itself or a simple call of another ISAPI Filter inside itself. This may occur if an ISAPI filter sends a response by using either the ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADERS) or WriteClient.

We will consider two cases:

  • The call was from a RAW_DATA notification, either READ_RAW_DATA or SEND_RAW_DATA.
  • The call was from any other notification (non-RAW_DATA).

In both cases, all filters subscribe to the SEND_RESPONSE notification, which will be called if the ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADERS) was used.

If the call was from a RAW_DATA notification, then only filters with higher order than the filter that sent the response will be called in the SEND_RAW_DATA notification.

If the call was from any other notification, then the filter that sent the response and the filters with higher order will be called in the SEND_RAW_DATA notification.

For example, suppose you have 3 filters: Filter_Low with low priority, Filter_Medium with medium priority, and Filter_High with high priority. Filter_Low and Filter_High subscribed to SEND_RESPONSE and SEND_RAW_DATA. Filter_Medium subscribed to SEND_RESPONSE and SEND_RAW_DATA as well, but has also subscribed to another notification.

From its extra notification, Filter_Medium sends either ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient.

The way ISA will call the filters before the ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient return will be as follows:

  • If ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient is sent from RAW_NOTIFICATION, then only Filter_High will be called by the SEND_RAW_DATA notification.
  • If ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADER) or WriteClient is sent from a non-RAW_DATA notification, then both Filter_Medium and Filter_High will be called, but Filter_Low will not be called by the SEND_RAW_DATA notification.
  • If ServerSupportFunction(SF_REQ_SEND_RESPONSE_HEADERS) is sent from anywhere, then all filters that subscribed to SEND_RESPONSE will be called, including Filter_Low.


SF_REQ_SET_NEXT_READ_SIZE

This support function is used by raw-read Web (ISAPI) filters to set the number of bytes that will be read during the next read event.

BOOL WINAPI * ServerSupportFunction(
  PHTTP_FILTER_CONTEXT pfc,
  enum SF_REQ_TYPE SF_REQ_SET_NEXT_READ_SIZE,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current active HTTP transaction.
pData
Unused in this support function.
ul1
Specifies the size, in bytes, that will be read during the next read event.
ul2
Unused in this support function.

Remarks

This support function is meaningful only for filters that are responding to raw-read events and that return the status code SF_STATUS_REQ_READ_NEXT from their entry-point function HttpFilterProc.


WriteClient

Points to the WriteClient function that sends raw data back to the client. The WriteClient callback function is called by a Web (ISAPI) filter to send data to the client.

Note For more information on the correct usage of WriteClient, see SF_REQ_SEND_RESPONSE_HEADER.

The WriteClient function is declared as:

BOOL WINAPI * WriteClient(
  PHTTP_FILTER_CONTEXT pfc,
  LPVOID buffer,
  LPDWORD lpdwBytes,
  DWORD dwReserved
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT data structure that is associated with the current, active HTTP transaction.
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.


HTTP_FILTER_LOG

The ISA Web proxy service includes a pointer to this structure when it is writing information to a log file. If your filter must 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
The client's host name.
pszClientUserName
The client's user name.
pszServerName
The name of the server to which the client is connected.
pszOperation
The HTTP operation type.
pszTarget
The target of the HTTP command.
pszParameters
The parameters passed to the HTTP command.
dwHttpStatus
The HTTP return status.
dwWin32Status
The Win32® error code.
dwBytesSent
The number of bytes sent from the server to the client.
dwBytesRecvd
The number of bytes received by the server from the client.
msTimeForProcessing
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 the string pointers can be replaced. If string pointers are changed, the memory they point to must remain valid until the next filter notification. The AllocMem callback function in the HTTP_FILTER_CONTEXT structure can be used to ensure this.


HTTP_FILTER_PREPROC_HEADERS

The ISA Web proxy service includes a pointer to this structure when it is preprocessing a request's headers. If your filter must 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 must 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 status 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.


HTTP_FILTER_RAW_DATA

The ISA Web proxy service includes a pointer to this structure when it is either reading or sending raw data. If your filter must 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
Points to the data buffer.
cbInData
The amount of data in the buffer pointed to by pvInData.
cbInBuffer
The size of the buffer pointed to by pvInData.
dwReserved
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 modify the raw data being sent or received. (cbInData and cbInBuffer must also be appropriately updated if the pointer is replaced.) The new buffer memory must remain valid until the end of the request. The new buffer memory can remain valid by using AllocMem or by using a buffer owned by the filter. In addition, the filter must not attempt to free or otherwise deallocate the old pvInData pointer. Only the owner of the memory block is allowed to free the buffer.

Warning 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 event must be assigned at the Web proxy service level. They cannot be assigned to an individual Web site.


HTTP_FILTER_SEND_RESPONSE

Web (ISAPI) filters receive this notification immediately before they send headers to the client. The filter can inspect, modify, or add headers that 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.

Note SF_NOTIFY_SEND_RESPONSE is not used when the ISA Web proxy service sends a response. However, it is called when a filter generates a response itself by using ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADER).

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 must 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 status code.
dwReserved
A DWORD data type reserved for later use.


HTTP_FILTER_URL_MAP

This structure does not apply to the implementation of ISAPI by ISA Server.


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];
  DWORD dwFlags;
} HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;

Members

dwServerFilterVersion
The ISAPI version in use by the server.
dwFilterVersion
The version number of ISAPI used by the Web (ISAPI) filter. The version used by your filter can be set by using the HTTP_FILTER_REVISION definition from the httpfilt.h header file in the Windows 2000 SDK.
lpszFilterDesc
Points to a null-terminated string that provides a short description of the Web (ISAPI) filter.
dwFlags
Contains flags that indicate for which notification-event types the filter should be notified, and what the filter's priority is. See Event Notifications for a list of priority flag values.


Event Notifications

The following is a table of notifications for which a Web (ISAPI) filter can be registered. The notifications are shown in the order in which they most commonly occur.

Notification Constant | Meaning
SF_NOTIFY_READ_RAW_DATA | Occurs when data is being read from the client. May occur more than once per request.
SF_NOTIFY_PREPROC_HEADERS | Occurs immediately after IIS or ISA has preprocessed headers, but before the program begins to process header content.
SF_NOTIFY_URL_MAP | Occurs after IIS has translated a URL to a physical path on the server. This notification is irrelevant for the ISA Web proxy service because it does not have any physical URLs. However, it is provided as it was in Microsoft Proxy Server 2.0, for compatibility with earlier versions.
SF_NOTIFY_AUTHENTICATION | Occurs just before IIS or ISA authenticates the client.
SF_NOTIFY_AUTH_COMPLETE | In HTTP authentication scenario, this notification occurs just after IIS or ISA has determined that access is allowed for the request resource.
SF_NOTIFY_ACCESS_DENIED | Occurs just after IIS or ISA has determined that access is denied for the request resource, but before IIS or ISA has sent a response to the client.
SF_NOTIFY_SEND_RESPONSE | Occurs after the request has been processed by IIS, but before any headers are sent back to the client. This notification is not used when the ISA Web proxy service sends a response. However, it is called when a filter generates a response itself by using ServerSupportFunction (SF_REQ_SEND_RESPONSE_HEADERS).
SF_NOTIFY_SEND_RAW_DATA | Occurs as IIS or ISA sends raw data back to the client. May occur more than once per request.
SF_NOTIFY_END_OF_REQUEST | Occurs at the end of a request.
SF_NOTIFY_LOG | Occurs at the end of a request, just before ISA writes the transaction to the ISA log.
SF_NOTIFY_END_OF_NET_SESSION | Occurs when a network session with a client is ending.

In addition to the notification events, ISAPI makes use of flags relating to filter priority and port security settings.

Filter Priority Settings

Value | Meaning
SF_NOTIFY_ORDER_DEFAULT | Default priority (medium priority).
SF_NOTIFY_ORDER_LOW | Low priority.
SF_NOTIFY_ORDER_MEDIUM | Medium priority.
SF_NOTIFY_ORDER_HIGH | High priority.

Port Security Settings

Value | Meaning
SF_NOTIFY_SECURE_PORT | Notify the application only for connections over a secure port.
SF_NOTIFY_NONSECURE_PORT | Notify the application only for connections over a nonsecure port.


Error Codes

The following are the run-time error codes, defined in wspfwerr.h, that may be returned by ISA Server.

Message ID | Code | Explanation
FWX_E_TERMINATING | 0xC0040001L | The object is shutting down.
FWX_E_INVALID_ARG | 0xC0040002L | The argument is invalid.
FWX_E_ALREADY_IN_BLOCKING_OP | 0xC0040003L | The blocking operation is already started.
FWX_E_NOT_IN_BLOCKING_OP | 0xC0040004L | There is no blocking operation to be ended.
FWX_E_ALREADY_EXISTS | 0xC0040006L | You cannot create the object because an object with this name already exists.
FWX_E_BUFFERFULL | 0xC0040007L | Not all the data was appended to the buffer object because the buffer was full.
FWX_E_PROTOCOL_RULES_DENIED | 0xC0040008L | The protocol rules do not allow the user to use the specified protocol.
FWX_E_ALREADY_EMULATED | 0xC0040009L | The connection is already emulated by another filter.
FWX_E_BAD_CONTEXT | 0xC004000AL | The method was not called while handling any of the supported events.
FWX_E_NOT_SUPPORTED | 0xC004000BL | Modifying this property is not allowed for this session.
FWX_E_NOT_AUTHENTICATED | 0xC004000CL | Cannot perform the action because the session is not authenticated.
FWX_E_SITE_AND_CONTENT_RULES_DENIED | 0xC004000DL | The site and content rules do not allow the user to access the specified destination.
FWX_E_MIME_NEEDED | 0xC004000EL | The MIME type is required.


Globally Unique Identifiers

ISA supports these MMC-like extensions. The following table lists the ISA snap-in nodes, their globally unique identifiers (GUIDs) and the FPCSnapinNode properties of each node.

Node | GUID | FPCSnapinNode Property ParentArray | FPCSnapinNode Property ParentPolicy | FPCSnapinNode Property CurrentObject
FPC | 6E21FA00-0C06-11D2-9A4F-0060081E9D26 | N/A | N/A | E_NOINTERFACE
Arrays | 273843AD-B1B9-4145-BDEF-8F2EB9E52382 | N/A | N/A | E_NOINTERFACE
Array | 545beab0-0c13-11d2-9a4f-0060081e9d26 | This array | N/A | IFPCArray
AccessPolicy | 24E13C70-1BDE-11d2-AC22-0060973C0C94 | The containing array, or NULL for enterprise policy. | NULL for array policy, or the enterprise policy. | IFPCArrayPolicy
Access Policy Rule | 1DCBF42D-96B3-48d9-866C-F19D635339E2 | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rules. | IFPCSiteAndContentRule or IFPCProtocolRule or IFPCWebPublishingRule
Site and Content Rules | 0161C461-1BDE-11d2-AC22-0060973C0C94 | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rules. | IFPCSiteAndContentRules
Site and Content Rule | 1904c70c-5ea0-11d2-9a14-006094eb634c | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rule. | IFPCSiteAndContentRule
Protocol Rules | CDD3D751-1C81-11d2-AC22-0060973C0C94 | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rules. | IFPCProtocolRules
Protocol Rule | 060fde66-3042-11d2-9a06-006094eb634c | The containing array, or NULL for enterprise policy. | The containing enterprise policy, or NULL for an array local rule. | IFPCProtocolRule
Web Publishing Rules | 29775731-16F5-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCWebPublishingRules
Web Publishing Rule | e224bd7c-a491-11d2-9a1c-006094eb634c | The containing array | N/A | IFPCWebPublishingRule
IP Packet Filters | 16985841-171E-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCIpPacketFilters
IP Packet Filter | 30984c30-fbce-11d2-aa2b-00a0c9d05606 | The containing array | N/A | IFPCIpPacketFilter
Policy Elements | BC17E262-1992-11d3-864F-0090272F9EEB | The containing array, or NULL for the enterprise schema. | N/A | IFPCPolicyElements
Schedules | 569b5e0e-d9f3-11d2-9a1e-006094eb634c | The containing array | N/A | IFPCSchedule
Schedule | 173f40a0-d9f2-11d2-9a1e-006094eb634c | The containing array | N/A | IFPCSchedule
Bandwidth Priorities | 582242B7-5BCB-4e17-9D09-A7E394A9C426 | The containing array | N/A | IFPCBandwidthPriorities
Bandwidth Priority | 03869EDB-8558-46d1-BF8E-CF08FF80D9B6 | The containing array | N/A | IFPCBandwidthPriority
Destination Sets | 1f3bb926-6cda-11d2-9a15-006094eb634c | The containing array | N/A | IFPCDestinationSets
Destination Set | 6145fc14-6cda-11d2-9a15-006094eb634c | The containing array | N/A | IFPCDestinationSet
Client Address Sets | f5813a0c-f0d7-11d2-9a24-006094eb634c | The containing array | N/A | IFPCClientAddressSets
Client Address Set | ccf9400c-f0d7-11d2-9a24-006094eb634c | The containing array | N/A | IFPCClientAddressSet
Protocol Definitions | 75032bd0-20a4-11d2-9a54-0060081e9d26 | The containing array | N/A | IFPCProtocolDefinitions
Protocol Definition | cc0b8e42-29f9-11d3-8a5b-006094eb634c | The containing array | N/A | IFPCProtocolDefinition or IFPCFilterProtocol; depends on object type.
Content Groups | 0223e789-aa75-42aa-a959-7773e41ac062 | The containing array | N/A | IFPCContentGroups
Content Group | a8c24098-72c2-4c1d-aaec-10e889723353 | The containing array | N/A | IFPCContentGroups
Dial-up Entries' | A9B94A88-4943-46ca-B88F-240F5B8BE6E0 |  |  | IFPCDialupEntries
Dial-up Entry | 8714C09D-E388-4190-A18E-6A340C2FD557 |  |  | IFPCDialupEntry
Servers | 5301D860-1AE6-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCServers
Server | 2EA65550-1AE6-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCServer
Logs | c6a42b60-0de3-11d3-aa33-00a0c9d05606 | The containing array | N/A | IFPCLogs
Log | f03e4a60-0df6-11d3-aa33-00a0c9d05606 | The containing array | N/A | IFPCLog
Monitoring | F1BAF761-823D-4c68-A7C3-463CC696BDD9 |  |  | IFPCArray
Alerts | 16985850-171E-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCAlerts
Alert | fe6eb072-1777-11d3-95a0-0004ac3db3cc | The containing array | N/A | IFPCAlert
Web (ISAPI) Filters | 4A0B8651-A3C5-4064-A783-2E06AA23721F | The containing array | N/A | IFPCWebFilters
Web (ISAPI) Filter | 6A4EC987-E775-41dc-A9D2-27226853D391 | The containing array | N/A | IFPCWebFilter
Drives | 6f9f8dc0-1cc4-11d3-aa34-00a0c9d05606 | The containing array | N/A | IFPCCacheConfiguration
Cache Drive | e89d86e0-1cc3-11d3-aa34-00a0c9d05606 | The containing array | N/A | IFPCServer
Client Configuration | 18612e10-23e1-11d3-aa35-00a0c9d05606 | The containing array | N/A | IFPCClientConfig
Web Browser | 84058b10-23f1-11d3-aa35-00a0c9d05606 | The containing array | N/A | IFPCWebBrowserClientConfig
ISA Firewall Client | E33492B6-DDD4-4631-BFB7-7EC1CAD944C1 | The containing array | N/A | IFPCFirewallClientConfig
Application Filters | 7452e8e4-29f9-11d3-8a5b-006094eb634c | The containing array | N/A | IFPCApplicationFilters
Application Filter | 02a589b8-29f9-11d3-8a5b-006094eb634c | The containing array | N/A | IFPCApplicationFilter
Network Configuration | fdbc5130-01f8-11d3-aa2f-00a0c9d05606 | The containing array | N/A | IFPCNetworkConfiguration
Local Domain Table (LDT) | a2095b50-01f3-11d3-aa2f-00a0c9d05606 | The containing array | N/A | IFPCLDT
Local Domain Table Entry | 138a1240-020e-11d3-aa2f-00a0c9d05606 | The containing array | N/A | IFPCLDTEntry
Local Address Table (LAT) | e52bbe10-06a2-11d3-aa31-00a0c9d05606 | The containing array | N/A | IFPCLAT
Local Address Entry | eae15160-06e2-11d3-aa31-00a0c9d05606 | The containing array | N/A | IFPCLATEntry
Routing | D72690B0-1C80-11d2-AC22-0060973C0C94 | The containing array | N/A | IFPCRoutingRules
Routing Rule | d3f2b790-31f9-11d2-a9ea-00a0c9d05606 | The containing array | N/A | IFPCRoutingRule
Policies | d6cc2b73-90e5-4050-afe0-48fc89df9402 |  |  | IFPCEnterprisePolicies
Enterprise Policy | 1e5743b0-45ac-41bf-be43-1e6cb6d99503 | N/A | N/A | IFPCEnterprisePolicy
Enterprise | 8d167b45-0a35-400c-b680-f44ddf0ca7f8 | N/A | N/A | IFPCEnterprise
Monitoring | F1BAF761-823D-4c68-A7C3-463CC696BDD9 |  |  | IFPCArray
Signaled Alerts | 1F199288-7C9E-46e9-9800-840248005605 |  |  | IFPCArray
Signaled Alert | 641893D7-0DC5-4ca6-8A7B-AE784AB0B915 |  |  | IFPCSignaledAlert
Services | A4FC6565-992C-488d-9D6E-9C6F48D96755 |  |  | IFPCArray
Service | 0689FFEB-5F95-4090-A7C6-032542D5A6C1 |  |  | IFPCServer
Sessions | 60DEA196-CEC1-4fec-B4CC-0DD6594C0D21 |  |  | IFPCArray
Session | 41BF2420-6EBE-481f-8F9C-8D333E56A758 |  |  | IFPCWebSession or IFPCFirewallSession
Publishing | 4a5530fc-5fc6-4d81-a5a7-e192bdd45dc8 |  |  | IFPCPublishing
Server Publishing Rules | bc96f5d8-a2f9-444f-bf25-341e601b10c3 |  |  | IFPCServerPublishingRules
Server Publishing Rule | 47757a2e-960f-471a-9f43-4b66a128904d |  |  | IFPCServerPublishingRule
Bandwidth Rules | 0C61CE0F-23CF-4977-9AC8-9E395F36B1E6 |  |  | IFPCBandwidthRules
Bandwidth rule | 512B4FA0-0A41-4976-8107-8E24D34A1D77 |  |  | IFPCBandwidthRule
Cache Configuration | 6BB2AF2E-91B1-4090-8C89-81DD01F2F71F |  |  | IFPCCache
Scheduled content download jobs | FBA1E736-7614-4c49-A8A0-8C9B7A117465 |  |  | IFPCScheduledContentDownload
Scheduled content download job | CA0F5779-1016-4d33-B249-29E1A378E4D3 |  |  | FPCScheduledContentDownloadConfig
Monitoring Configuration | 173D69BE-C58F-4a4a-9498-8BB59FD350BD |  |  |
Extensions | 2FA40928-5067-4031-AD13-5F8AA3021447 |  |  | IFPCExtensions


Glossary

This glossary defines some of the terms found in the documentation for Internet Security and Acceleration (ISA) Server 2000. Click a letter to jump to that section of the glossary, or use your browser's Find command to search for a word across the entire glossary.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

access control entry (ACE)
An entry in an access control list (ACL). The entry contains a security identifier (SID) and a set of access rights. A process with a matching SID is either allowed or denied access rights.
access control list (ACL)
A level of Windows® 2000 permission that can be set on a file or a directory allowing specified users access within an NTFS directory. An access control entry (ACE) is an entry in the list.
access policy
A set of protocol rules and site and content rules that determines the behavior of an enterprise or array. In the case of an array, access policy also includes packet filters.
active caching
A mechanism used to automatically initiate new requests to update cached file objects without user intervention. Requests can be activated based on the length of time an object has been cached or was last retrieved from the object's source location. This type of caching can be used to ensure the freshness of specified data within the cache. See also passive caching, fresh data.
address spoofing
See DNS spoofing.
alerting
This feature alerts administrators about suspicious network events, such as rejected packets, protocol violations, and a full hard disk. Alerting is enabled when IP packet filtering is turned on and is recorded in the IP packet filtering logs. Event messages can also be sent to a user account by using an SMTP e-mail message.
allow filter
An IP packet filter that allows access between specified IP addresses at the specified ports and using the specified protocols.
anonymous logon
This feature allows a user remote access to a computer on the Internet without supplying a user name or password but provides only the guest permissions assigned to that account. Commonly used in FTP requests. See also IUSR_computername.
API
Application programming interface, a set of routines used by an application to direct the performance of procedures by a computer's operating system.
application filter
A firewall extension that registers for and processes events related to connection with another network. Application filters are typically designed to enhance the security provided by a firewall by excluding or modifying data that approaches the network.
application gateway
Computer software intended to maintain security on a secluded network yet allow certain traffic to go between the private network and the outside world. See also firewall.
ARCNet
Attached Resource Computer Network, a type of local area network.
array
A group of ISA server computers used to provide distributed caching, load balancing, and fault tolerance. Arrays allow client requests to be distributed among several ISA server computers, which increases response time for clients. Arrays allow a group of ISA server computers to be treated and managed as a single, logical entity. Array communications are peer-to-peer, not hierarchical, one-way communication between upstream and downstream ISA server computers.
array member
An ISA server computer that is part of an array.
array membership table
A list of ISA server computers within an array. Each ISA server computer manages its own table.
asynchronous input/output
Asynchronous input/output (asynchronous I/O) allows some I/O functions to return immediately, even though an I/O request is still pending. Asynchronous I/O enables an application to continue with other processing and wait for the I/O to be completed at a later time. Asynchronous I/O is also called overlapped I/O.
authentication
Validation of a user's logon information to determine permission to access a resource or perform an operation. See also anonymous logon, basic authentication, and Windows 2000 challenge/response authentication.
autodial
A component of ISA that enables users to automatically connect to remote networks, such as the Internet, during predetermined times.


B

backup domain controller (BDC)
A server that receives a copy of the security policy and master database for a Windows 2000 domain. The master database contains centralized security data for all domain-assigned users and is updated when changes in security are made. See also primary domain controller (PDC), member server.
bandwidth
The data transfer capacity of a digital communications system.
bandwidth control
The practice of setting the maximum network capacity that a service is allowed to use. You can deliberately limit a server's workload by not allowing it to receive requests at full capacity, saving resources for other programs, such as e-mail.
basic authentication
A method of authentication that encodes the user name and password. Basic authentication is called "clear text" because the encoding (base-64) can be decoded by anyone with a freely available decoding utility. Note that encoding is not the same as encryption. See also Windows 2000 challenge/response authentication.
BDC
See backup domain controller (BDC).
BIND service
See Domain Name System (DNS).
binding
A process that establishes the initial communication channel between the protocol driver and the network adapter driver.
bitmask
A numeric value intended for a bit-by-bit value comparison with other numeric values, typically to flag options in parameters or return values. Usually this comparison is done with bitwise logical operators, such as And and Or in Visual Basic, and ampersand (&) and pipe (|) in C++.
bits-per-second (bps)
The basic rate of data transmission.
block filter
An IP packet filter that completely blocks access to specific ports or from specific IPs.
BOOTP
See bootstrap protocol (BOOTP).
bootstrap protocol (BOOTP)
A Transmission Control Protocol/Internet Protocol (TCP/IP) protocol that allows a diskless client computer to determine its own Internet Protocol (IP) address, the IP address of the server, and the name of a file to be loaded into memory and executed. DHCP provides a superset of the functions provided by BOOTP.
BPS
See bits-per-second (bps).
broadcasting
The delivery of data packets to all computers on a network.
browser
A tool for navigating and accessing information on either the Internet or an intranet.


C

cache
A store of frequently retrieved objects and URLs located on the cache drive of an ISA computer. Instead of retrieving an object directly from an Internet Web server, the object is stored and retrieved from the cache instead. Caches improve network performance by reducing the number of objects retrieved from the Internet based on their popularity.
cache drive
The amount of space reserved on a selected server disk drive for use in storing cached files.
cache filtering
The ability to either cache or not cache objects retrieved from World Wide Web (WWW), FTP, or Gopher sites.
cache routing
The forwarding of a client HTTP request from one ISA computer to another ISA computer. Also known as cascading or chaining. See hierarchical caching.
CERN-Proxy Protocol
An industry standard for application-aware proxy services over HTTP-based client/server communications. CERN standards are established by the European Laboratory for Particle Physics (CERN), located in Switzerland.
CGI
See Common Gateway Interface (CGI).
chaining
A method to link multiple ISA computers together. Individual ISA computers and arrays or any combination can be chained. Communication is in an upstream, hierarchical order.
challenge/response
See Windows 2000 challenge/response authentication.
clear text
See basic authentication.
COM object
A programming structure that includes both data and functionality. A COM object is defined and allocated as a single unit. The only public access to a COM object is through the programming structure's interfaces. At a minimum, a COM object must support the IUnknown interface, which maintains the object's existence while it is being used and provides access to the object's other interfaces.
commit rate
The speed with which objects or URLs are added to the cache.
Common Gateway Interface (CGI)
A standard interface for HTTP server applications. Used by an application that runs on a server to generate dynamic content based on parameters sent by the requesting Web browser.
completion port
A Windows object that efficiently manages threads used for asynchronous I/O.
connected service
A service that provides a managed connection allowing networked computers to communicate reliably. (Also known as streamed service.) TCP and SPX protocols support this type of service. Four important characteristics include:
  • The path for data packets is established in advance.
  • The resources required for a connection are reserved in advance.
  • A connection's resources are reserved throughout the life of that connection.
  • When a connection's data transfer is completed, the connection is terminated and the allocated resources are freed.
connectionless service
A service that emphasizes broadcasting and unacknowledged delivery of data packets. Supports higher throughput speeds for real-time applications. UDP is a protocol that supports this type of service.
credentials
An authentication method used to validate client-to-server and server-to-server communication. Credentials include a user name and a password that is used to validate requests from client computers or from other computers in an array or chain.


D

data filter
An application filter that monitors content, as in a check for viruses, and that can also modify content.
data packet
A sequence of binary digits, including data and control signals, that is transmitted and switched as a composite whole. The data, control signals, and, possibly, error control information are arranged in a specific format.
Data Source Name (DSN)
The logical name that allows a connection to an ODBC data source, such as a SQL Server database.
demand-dial connectivity
A process used by Autodial to perform on-demand dialout connections either to an Internet service provider or to a corporate office from a branch office.
DHCP
See Dynamic Host Configuration Protocol (DHCP).
DHCP relay agent
The component that relays DHCP and BOOTP broadcast messages between a DHCP server and a client across an IP router.
dial-up networking
A component of Windows 2000 and Windows 95/98 that enables users to connect to remote networks, such as the Internet or an internal network, over a telephone line.
discretionary access-control list (DACL)
A list that is controlled by the owner of an object and that specifies the access that particular users or groups can have to the object.
distributed caching
The caching of Internet objects in an array or chain of ISA computers, providing load balancing and fault tolerance. Client requests are sent through the array, to upstream ISA computers, or any combination thereof.
DNS
See Domain Name System (DNS).
DNS spoofing
The practice of assuming the DNS name of another system either by corrupting a name-service cache or by compromising a domain-name server for a valid domain.
domain filtering
Controlling access to specific Internet sites by denying or granting permission based on the Internet computer's domain name or friendly name.
domain name
The computer name that substitutes for a network IP address. For example, www.microsoft.com instead of the IP address 157.45.60.81. Also called the friendly name. See also Domain Name System (DNS).
Domain Name System (DNS)
A protocol and computer-naming hierarchy used throughout the Internet to map computer IP addresses to their domain names. DNS is sometimes referred to as the BIND service.
downstream/upstream routing
The routing of a response from one ISA computer to another ISA computer. Client computers connecting to an ISA computer are always downstream. A request from a client computer always flows upstream to ISA computers until the requested item is found, whether it is in the cache of an ISA computer or from the Internet. ISA sends the response downstream to the client computer.
driver
A software component that allows a computer to send and receive information to and from a hardware device.
DSN
See Data Source Name (DSN).
dual-homed
Having connections to two separate physical networks. Each ISA computer in an array has both an internal and external network adapter for Internet connectivity. The internal adapter connects to the internal network. The external adapter connects to the Internet.
dynamic addressing
The automatic assignment of IP addresses in a changing network.
dynamic filters
Dynamic filters are automatically started by the Firewall service, Web proxy, or SOCKS proxy service. This feature allows the ISA services to automatically open and close communication ports on the external interface when transmission of packets is needed.
Dynamic Host Configuration Protocol (DHCP)
A protocol that offers dynamic assignment of IP addresses and related information for temporarily connected network users. DHCP provides safe, reliable, and simple TCP/IP network configuration, prevents address conflicts, and helps conserve the use of IP addresses through centralized management of address allocation.


E

encryption
The process of making information indecipherable to protect it from unauthorized viewing or use, especially during network transmission or when it is stored on a transportable magnetic medium.
Ethernet
A widely used LAN developed by Xerox, Digital, and Intel. Ethernet networks connect up to 1,024 nodes at 10 megabits per second over twisted pair, coaxial cable, and optical fiber.
extension mode snap-in
A snap-in that provides functionality only when invoked by a parent snap-in. Extension snap-ins can add nodes to the namespace, or just extend existing nodes with new menus, toolbars, property pages, wizards, or Help.


F

FAT
See file allocation table (FAT).
fault tolerance
The ability of ISA servers in a domain array to take over the responsibilities of a failed server.
file allocation table (FAT)
A table or list maintained by some operating systems to keep track of the status of various segments of disk space used for file storage. See also Windows 2000 file system (NTFS).
file transfer protocol (FTP)
The Internet standard protocol for transferring files between computers. FTP uses the Telnet and TCP protocols. The server requires a client to supply a logon user name and password before honoring requests. See also anonymous logon.
filter
A means of excluding information that does not match a predefined set of specifications. See application filter.
firewall
A security system intended to protect an organization's network against external threats, such as hackers, coming from another network, such as the Internet. See also application gateway.
Firewall service
An API service used by ISA Server that provides redirection and remote execution of Windows Sockets (Winsock) applications over connections involving a computer on an internal network (intranet) computer and remote computers on the Internet.
Firewall service completion port
A completion port created by Windows 2000 at the request of the Firewall service that is associated with the proxy. See completion port.
FQDN
See fully qualified domain name.
forward proxy
A Web proxy scenario where internal clients access the Internet.
fresh data
Cached data that is verified to be current and consistent with its source.
FTP
See File Transfer Protocol (FTP).
fully qualified domain name (FQDN)
In TCP/IP, host names with their domain names appended to them. For example, a computer with host name zebra and domain name microsoft.com has an FQDN of zebra.microsoft.com. See also Domain Name System (DNS).


G

gateway
A device that routes data packets between multiple TCP/IP networks having dissimilar transport protocols. ISA can act as a gateway between an internal network (an intranet) and the public network (the Internet). See also router.
Gopher
A hierarchical system for finding and retrieving information from the Internet or an intranet. An enhanced version, Gopher Plus, returns more information about an item, such as file size, last date of modification, and the administrator's name. A display of all files available on a Gopher server is called the Gopherspace.
group
In a Windows 2000 Server network, an account containing user accounts that are called members. The permissions and rights granted to a group are also provided to its members, making groups a convenient way to grant common capabilities to collections of user accounts. Groups are assigned unique names within a domain.
GUID
Globally unique identifier, a 128-bit value that uniquely identifies objects such as OLE servers, interfaces, manager entry-point vectors, and client objects.


H

H.323 Protocol
The International Telecommunications Union - Telecommunications (ITU-T) standard protocol for real-time multimedia communications and conferencing over packet-based networks.
hash
A mathematical algorithm used for routing client requests within an array or a chain. The result of the hash determines which specific ISA computer to send the client request.
header
In data packet communications, a specified number of bytes that precedes the actual data being transmitted. It identifies control information used to deliver, route, and process the data contents of a packet.
hierarchical caching
The forwarding of a client HTTP request from one ISA computer to another ISA computer upstream. The downstream (source) ISA computer forwards client requests that it cannot service from its own cache. Hierarchical caching uses upstream routing and is a subset of distributed caching.
hierarchical chaining
Linking multiple ISA computers together to form a chain. Individual ISA computers, arrays, or any combination can be chained.
hit rate
The percentage of client requests fulfilled through previously cached data, in contrast to the total of all client requests that have been processed by the caching service.
home directory
See root directory.
host name
The name given to a computer that is part of a Windows 2000 network domain and used for client authentication. Also called the computer name. See also fully qualified domain name (FQDN).
HOSTS file
See LMHOSTS file.
HTML
Hypertext Markup Language (HTML). A markup language derived from the Standard Generalized Markup Language (SGML). Used to create a text document with formatting specifications that tells a software browser how to display the page or pages included in the document.
HTTP
The client/server protocol used to access information on the Web.
HTTP Redirector filter
A Hypertext Transfer Protocol (HTTP) redirector filter provided with ISA, that forwards HTTP requests from Firewall and secure network address translation (SecureNAT) clients to the Web proxy service.


I

ICMP
See Internet Control Message Protocol.
IIS
See Internet Information Services.
IMC
See Internet Mail Connector.
inbound access
Ability to send information from an external network, such as the Internet, to an internal or external network. See also outbound access.
Integrated Services Digital Network (ISDN)
A dial-up connection to the Internet installed by your Internet service provider (ISP) or telephone company. An ISDN line can offer speeds up to 128,000 bits-per-second (bps) and must be installed at both the server site and the remote site.
interactive application
A program written in C, Perl, or as a Windows 2000 batch file. The user initiates the program by clicking a link in a hypertext document.
Internet Control Message Protocol (ICMP)
The Internet standard protocol subset of IP that handles control and error messages. Gateways use ICMP to send problem reports on packets back to the source that sent the packet.
Internet Information Services (IIS)
The Microsoft® Internet server feature designed for implementing and managing Web sites. Although IIS supports multiple protocols, it primarily transmits information in HTML pages by using HTTP. ISA integrates fully with IIS and Windows 2000 Server.
Internet Mail Connector (IMC)
A component of Microsoft Exchange Server that runs as a Windows 2000 Server service. You can use the Internet Mail Connector to exchange information with other systems that use the Simple Mail Transfer Protocol (SMTP).
Internet Protocol (IP)
The Internet standard routing protocol that defines the IP datagram as the unit of data transfer and provides the IP address scheme to route packets from one network location to another. IP includes the ICMP protocol. The Internet protocol suite is often called TCP/IP.
Internet Relay Chat (IRC)
An Internet standard protocol that supports interactive, real-time, text-based communications in established "chat rooms" on the Internet by means of IRC servers.
Internet Server Application Programming Interface (ISAPI)
A Microsoft-developed API for establishing procedural calls between Internet-based applications and the underlying operating system.
Internet Service Manager
The tool used with Internet Information Services (IIS) to administer services.
Internetwork Packet Exchange (IPX)
A routing protocol developed for Novell Netware networks that is used in place of IP to manage data transfer between computers. Windows NT and Windows 2000 implement IPX through NWLink.
IP
See Internet Protocol.
IP address
A unique address that identifies a computer on a network by using a 32-bit address that is unique across a TCP/IP network. An IP address is usually represented in dotted-decimal notation, which depicts an octet (8 bits, or 1 byte) of an IP address as its decimal value and separates each octet with a period; for example, 102.54.94.97.
IP forwarding
IP forwarding (IP routing) normally allows packets to be forwarded on the internal network.
IP packet filtering
Filtering that either allows or blocks packets destined to specific services on or behind the ISA computer.
IP packet filtering log
The log where IP packet filter events are recorded. The file is identified with PF as the first two letters in the log file name.
IPX/SPX
See Internetwork Packet Exchange (IPX), Sequenced Packet Exchange (SPX).
IRC
See Internet Relay Chat.
ISA Management
The interface tool used to manage ISA Server enterprise, arrays and standalone servers.
ISAPI
See Internet Server Application Programming Interface.
ISDN
See Integrated Services Digital Network.
ISDN interface card
Similar in function to a modem, an ISDN card is hardware that enables a computer to connect to other computers and networks on an Integrated Services Digital Network (ISDN).
IUSR_computername
A default account with anonymous logon privileges for accessing Internet-based services such as FTP, WWW, and Gopher. This account is created during the installation of Internet Information Services (IIS).


K

keep-alives
A keep-alive message is a type of broadcast message, supported by both the client and the server, that determines whether an idle connection is still active. After a network service completes an initial connection request, it uses keep-alive messages to keep the idle connection available for subsequent requests. As a performance-optimizing feature, keep-alive messages avoid the substantial cost of establishing and terminating connections.


L

LAT
See Local Address Table.
Layered Service Provider (LSP)
A service that provides higher-level custom communication functions and relies on services provided by an underlying base provider. In ISA, the Firewall client software is a layered service provider that extends Winsock 2 from the client to the ISA server and uses the underlying base TCP/IP service provider to communicate to the ISA server.
LMHOSTS file
A text-based file that maps IP addresses to the friendly names of Windows 2000 computers. This file is used as a static routing table in Windows 2000 Server to authenticate and register valid nodes in a local TCP/IP network.
load balancing
Load balancing distributes client requests among ISA Server computers. If one ISA Server computer is unavailable, another server can accept the request, preventing an interruption in service.
Local Address Table (LAT)
A table of all internal IP address pairs on the internal network where ISA is installed. This list is used to control access between clients on the internal network and remote IP addresses on external IP networks (or the Internet). The LAT is registered and stored in a text-based file within the installed directory for ISA. This file is distributed to clients during setup and updated periodically by ISA.


M

management information database (MIB)
A standard database component that uses the Simple Network Management Protocol (SNMP) protocol to communicate information about hardware and software processes on your network for further management and monitoring.
member server
A server that has been assigned to a Windows 2000 domain but is not designated as either the primary domain controller (PDC) or the backup domain controller (BDC) within the assigned domain.
MIB
See management information database (MIB).
Microsoft Management Console (MMC)
General, ISV-extensible common management console in Windows 2000. The MMC console is a Windows-based multiple document interface (MDI) application. MMC itself provides no management behavior, but instead provides a common environment for snap-ins, which provide the actual management functionality.
MIME
See Multipurpose Internet Mail Extensions.
MMC
See Microsoft Management Console.
mode of extensibility
Behavior that a snap-in provides, extending the console with more functionality. Microsoft has defined several modes of extensibility, and every snap-in must provide at least one of those modes.
.msc file
A "Management Saved Console" file that constitutes a tool. After an administrator has assembled a tool using various snap-ins, the administrator can save the tool in an .msc file, which can be opened and used again later. An .msc file can be passed on to another administrator. Any administrator can open the .msc file in MMC, causing the tool to be loaded.
multihomed
A computer with network connections to multiple separate physical networks.
Multiple Document Interface (MDI)
An interface that supports multiple simultaneous views, or windows. A Single Document Interface (SDI), such as Microsoft Internet Explorer, does not support multiple views.
Multipurpose Internet Mail Extensions (MIME)
A way of configuring browsers to view files that are in multiple formats. MIME permits the exchanging of objects, different character sets, and multimedia in e-mail on different computer systems.


N

name resolution
The process of mapping a computer name (friendly name) into its corresponding numeric IP address.
namespace
A tree-formatted, ordered list of all the nodes available in the current tool. The display of the namespace is similar to a folder and directory structure on a hard drive. Required for the Domain Name System (DNS) to work properly. The DNS namespace is hierarchical in nature and allows host names to be stated in absolute or relative terms. Absolute names, or fully qualified domain names (FQDNs), are defined from the root of the name space and uniquely identify a node in the hierarchy. Relative names are represented relative to a name in the hierarchy.
negative caching
The caching of HTTP error conditions associated with accessing a particular URL. If the URL is unavailable, the error response message can be cached and returned to subsequent clients that request the same URL.
NetBIOS
See network basic input/output system (NetBIOS).
NetBIOS Extended User Interface (NetBEUI)
A network protocol usually used in small, department-sized local area networks (LANs). It can use Token Ring source routing as its only method of routing. See also network basic input/output system (NetBIOS), router.
network address translation (NAT)
The process of converting between IP addresses used within an intranet or other private network and Internet IP addresses. See also SecureNAT.
network basic input/output system (NetBIOS)
An API that can be used by applications on a local area network (LAN). NetBIOS provides applications with a uniform set of commands for mapping input/output (I/O) operations into equivalent network operations.
Network News Transfer Protocol (NNTP)
The Internet standard protocol for posting, distributing, and reading network news messages posted among news groups on the Internet. Messages are posted to NNTP servers and are accessed by NNTP clients (newsreaders).
NNTP
See Network News Transfer Protocol (NNTP).
NTFS File System
An advanced file system used by Windows NT/Windows 2000 that supports file system recovery, very large storage media, and object-oriented applications. NTFS also offers enhanced security over the older FAT file system.
NWLink IPX/SPX Compatible Transport
A standard network protocol that supports routing and allows Novell NetWare client/server applications to communicate with IPX/SPX applications.


O

Open Database Connectivity (ODBC)
ODBC is an API that enables applications to access data from a variety of database systems.
outbound access
Ability to send information from an internal network to an external network, such as the Internet. See also inbound access.


P

package
Snap-ins collected into a unit for shipment by a software vendor.
package definition file (PDF)
A file used by Microsoft Systems Management Server for automatic installation of client software. The PDF can also be used for automatic uninstallation of client software for 32-bit Windows-based clients.
passive caching
In this type of service, data is cached and discarded entirely on the basis of object size, popularity, or time since the requested object was last updated in the cache. Frequently referred to as on-demand caching because all caching updates are user-initiated. See also active caching.
password authentication
See authentication.
PDC
See primary domain controller.
PDF
See package definition file (PDF).
Peer Web Services
A collection of services that enable a computer running Windows NT Workstation/Windows 2000 Professional to publish a personal Web site from the desktop. These services include WWW, FTP, and Gopher services.
phonebook entry
Used to dial the access number of an Internet service provider (ISP) by using Remote Access Service (RAS) from the Autodial service.
ping
A TCP/IP utility that verifies connections to one or more remote computers by sending ICMP packets and listening for reply packets.
plug-ins
Third-party applications that are installed to extend and enhance the functionality of ISA.
Point-to-Point Protocol (PPP)
In contrast to SLIP, this more recently established Internet communications protocol standardizes dial-up networking that uses analog modem hardware and standard telephone lines. Although PPP is a well-standardized protocol, vendor implementations of PPP service can vary significantly.
Point-to-Point Tunneling Protocol (PPTP)
A newer networking protocol that enables remote users to access corporate networks securely across the Internet by dialing into an Internet service provider (ISP) or by connecting directly to the Internet. PPTP supports multiprotocol virtual private networks (VPNs). Because PPTP allows multiprotocol encapsulation, users can send any packet type over an IP network.
popularity
A measure of the frequency with which objects or URLs are requested by client applications, such as Web browsers. See also cache.
port number
A number that identifies a certain Internet application with a specific connection. Ports are used in TCP to name the ends of logical connections that carry long-term conversations. See also well-known port number.
Post Office Protocol (POP)
A network protocol that permits a client computer to access e-mail on a server. Usually, this means that a POP3 server is used to allow a client computer to retrieve mail that an SMTP server is holding for it.
primary domain controller (PDC)
A server assigned to authenticate logons and maintain the security policy for a Windows 2000 domain. This server stores the master database of all domain-assigned security data for users and must be updated when changes in security are made. See also backup domain controller (BDC), member server.
protocol
Software that allows computers to communicate over a network. The Internet protocol is TCP/IP.
proxy
A software program that connects a user to a remote destination through an intermediary gateway.
proxy client
A client computer that must use a proxy server to gain access to network services not directly supported for client usage.
proxy server
A computer that acts as a relay between remote servers and clients to intercept requests and process communications on behalf of proxy clients.
publishing
The process that allows computers remote from an ISA computer to publish to the Internet. Publishing includes reverse hosting and secure Web publishing.


Q

Quality of Service (QoS)
A set of quality-assurance standards and mechanisms for data transmission implemented in Windows 2000.


R

RAS
See Routing and Remote Access Service.
remote administration
The practice of administering a computer from another computer connected across the network.
remote procedure call (RPC)
A message-passing facility that allows a distributed application to call services available on various computers in a network. Used during remote administration of computers.
remote socket
An external socket on the firewall that listens to or connects to the Internet. The remote socket represents the client's internal socket.
retrieve rate
The speed with which objects or URLs are taken from the cache.
reverse hosting
The process by which any server sitting behind ISA can publish to the Internet. See also secure Web publishing and publishing.
root directory
The top-level directory of a disk's directory structure.
router
An intermediary device on a communications network that expedites message delivery.
routing
The process of forwarding packets to other routers. Routing is used with arrays to direct client requests for Internet objects. Routing is done in conjunction with arrays, chained ISA computers, or directly to the Internet.
Routing and Remote Access Service (RRAS)
A Microsoft-developed service that allows remote client computers running Microsoft dial-up networking, all Microsoft RAS clients, or any third-party PPP client to dial in to a network server (RAS server). RAS servers can also be configured to allow local client computers to dial out to servers outside an internal network.
Routing Information Protocol (RIP)
A protocol that enables a router to exchange routing information with a neighboring router.
RPC
See remote procedure call.


S

SAP Agent service
The service that allows IPX name resolution on Firewall client computers.
secure Web publishing
The process by which a server behind ISA can publish to the World Wide Web (WWW) without compromising security. See also reverse hosting and publishing.
SecureNAT
SecureNAT is an extension of the Windows 2000 NAT driver. ISA Server's secure network address translation (NAT) feature provides a degree of address transparency for networked clients. NAT substitutes a global IP address, valid on the Internet, for an internal IP address. ISA Server enhances the underlying NAT functionality in Windows 2000, by enabling access control for FTP, Windows NetMeeting for H.323, and T-120 protocols. It also enables rerouting HTTP requests, which can then frequently be satisfied by a local cache. This enhancement greatly improves HTTP performance and lowers bandwidth requirements.
Secure Sockets Layer (SSL)
A protocol that supplies secure data communication through data encryption and decryption. SSL enables communications privacy over networks.
Sequenced Packet Exchange (SPX)
A transport-level protocol developed for use in Novell NetWare networks. SPX is used in place of TCP to verify packet delivery, ensure proper sequencing of packet data, and provide connected service between devices on a network. See also Internetwork Packet Exchange (IPX).
Serial Line Internet Protocol (SLIP)
An older industry standard communications protocol that standardizes dial-up networking. See also Point-to-Point Protocol (PPP).
Server Message Block (SMB) protocol
The underlying protocol by which Microsoft Windows 2000-based servers communicate critical service information with one another.
Service Advertising Protocol (SAP)
In the Windows environment, SAP is a service that broadcasts shared files, directories, and printers categorized first by domain or workgroup, and then by server name.

In the context of routing and IPX, SAP is used by servers to advertise their services and addresses on the network. Clients use SAP to determine what network resources are available.

SID
A security identifier that is part of the access control entry (ACE).
Simple Mail Transfer Protocol (SMTP)
An Internet standard protocol used for exchanging e-mail messages between SMTP servers on the Internet.
Simple Network Management Protocol (SNMP)
A standard protocol used for monitoring your network. See also management information database (MIB).
site and content rules
Rules defined by the ISA administrator that establish whether content on specified destinations can be accessed by specific users and when the rule is in effect.
SMTP
See Simple Mail Transfer Protocol.
snap-in
Software that makes up the smallest unit of console extension. One snap-in represents one unit of management behavior (for example, the Windows 2000 event log viewer is a functional unit of management and thus a good candidate to become a snap-in). Technically, snap-ins are OLE InProc servers.
SNMP
See Simple Network Management Protocol.
socket
A logical communications channel used by TCP/IP applications. Sockets are data structures created by using a combination of device IP addresses and reserved TCP/UDP port numbers to indicate connection and delivery service information. See also Windows Sockets.
SOCKS
A protocol for traversing firewalls in a secure and controlled manner, made available to the public by the Internet Engineering Task Force (IETF).
SPX
See Sequenced Packet Exchange.
SQL server
A server that uses the structured query language (SQL) to query, update, and manage a relational database.
SSL
See Secure Sockets Layer.
stand-alone mode snap-in
A snap-in that provides functionality even if loaded alone in a console that has no other snap-ins.
static filters
Filters that allow packets from other administrator-selected services from the Internet. A static filter is created during configuration of ISA by using the user interface. If IP packet filtering is enabled, the static filter is always on.
static IP mapping
A method provided on a WINS server to assign a static (unchanging) IP address to a client.
structured query language (SQL)
A database query and programming language widely used for accessing data in, querying, updating, and managing relational database systems. See also SQL server.
subnet mask
A TCP/IP configuration parameter that extracts network and host configuration from an IP address. This 32-bit value enables the recipient of IP packets to distinguish the network ID portion (domain name) of the IP address from the host ID (host name).
system access-control list (SACL)
A list that controls the generation of audit messages for attempts to access a securable object. The ability to get or set an object's SACL is controlled by a privilege typically held only by system administrators.
Systems Management Server (SMS)
A Windows 2000 Server network server application that remotely manages the computers on a network. SMS detects computers on the network, inventories software and hardware configurations, and installs client applications from a central location.


T

TCP/IP
See Transmission Control Protocol/Internet Protocol.
Telnet
The Internet standard protocol for remote terminal connection service. Telnet allows a user to interact with the remote computer as if the user was on a terminal directly connected to the remote computer.
Time-to-Live (TTL)
A standard field in a TCP/IP header that indicates an age-of-expiration value that is examined by receiving stations. Data with active TTL values is maintained and forwarded on the network; data with expired TTL values is discarded.
token ring
A type of network media that connects clients in a closed ring and uses token passing to enable clients to use the network.
Transmission Control Protocol (TCP)
The Internet standard transport protocol that provides the reliable, two-way connected service that allows an application to send a stream of data end-to-end between two computers across a network. The Internet protocol suite is often called TCP/IP.
Transmission Control Protocol/Internet Protocol (TCP/IP)
A family of networking protocols that allows computers with diverse hardware architectures and various operating systems to communicate across interconnected networks and the Internet. TCP/IP includes standards for how computers communicate and conventions for connecting networks and routing traffic. Every computer on the Internet supports TCP/IP.
TTL
See Time-to-Live.
tunneling
See Point-to-Point Tunneling Protocol.


U

UDP
See User Datagram Protocol.
Uniform Resource Locator (URL)
The address of a resource on the Internet. URL syntax is in the form protocol://host/localinfo, where protocol specifies the means of returning the object, such as Hypertext Transfer Protocol (HTTP) or File Transfer Protocol (FTP); host specifies the remote location where the object resides; and localinfo is a string — often a file name — passed to the protocol handler at the remote location.
User Datagram Protocol (UDP)
A standard transport protocol in TCP/IP networking that provides connectionless service for unacknowledged delivery of packets. UDP adds port addresses to the service provided by IP.


V

VDOLive
A stand-alone application that provides stream-oriented service for continuous video imaging. VDOLive Player can be configured to work with Internet Explorer.


W

Web proxy service
The service that provides a means for ISA to act as a proxy server.
well-known port number
The standard, default port numbers used by the Internet community for well known (commonly used) services. For example, the well known port number for the Gopher service is 70; for the World Wide Web service, it is 80.
Win32 Internet Extensions
A collection of functions contained in Wininet.dll that simplifies client access to the Internet by way of HTTP, FTP, and Gopher. The set of functions is an extension to the Win32® API.
Windows 2000 challenge/response authentication
A method of authentication in which a server uses Windows 2000 security to allow access to its resources.
Windows 2000 file system (NTFS)
See NTFS file system.
Windows 2000 Performance Monitor
A tool used by Windows 2000 to track computer activity by using a predefined set of counters.
Windows 2000 Server Event Viewer
A program provided with Windows 2000 that enables users to monitor system, security, and application events by viewing the Windows 2000 Event Log.
Windows 2000 System Event Log
A Windows 2000 service that records events in the system, security, and application service logs. See also Windows 2000 Server Event Viewer.
Windows Internet Name Service (WINS)
A name resolution service that runs on Windows 2000 Server. WINS maps friendly names to IP addresses. A WINS server handles name registrations, queries, and releases. See also Domain Name System (DNS).
Windows Script Host
A language-independent scripting host for Microsoft ActiveX® scripting engines.
Windows Sockets
A Windows implementation of the widely used University of California-Berkeley Sockets API. Windows Sockets (Winsock) is a networking API used to create TCP/IP-based sockets applications. Winsock provides interfaces between applications and the transport protocol and works as a bidirectional connection for incoming and outgoing data. See also socket.
WinInet
See Win32 Internet Extensions.
WINS
See Windows Internet Name Service.
Winsock
See Windows Sockets.


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.


Requirements

Many topics that introduce the syntax of an API element contain information about the build and run-time requirements for using the element. The format is as follows:

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in winuser.h.
Import Library: Use user32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

The first line indicates the versions of Windows NT on which an element is supported. This information may include required service packs, option packs, or components such as Internet Explorer. If an element is not supported, the line reads "Windows NT/2000: Unsupported."

The second line indicates whether an element is supported on Windows 95 or Windows 98. This information may include required OEM service releases, redistributables, or components such as Internet Explorer. If an element is not supported, the line reads "Windows 95/98: Unsupported."

The third line indicates the versions of Windows CE on which an element is supported. If an element is not supported, the line reads "Windows CE: Unsupported."

The fourth line indicates the file that defines an element. This value can be an .h file, .idl file, or .odl file. If the header file is supplied by the user, the line reads "Header: User-defined."

The fifth line indicates the file used to resolve calls to a function or member. This value can be a .lib file, .dll file, or .tlb file. If the import library is supplied by the user, the line reads "Import Library: User-defined." For element types that do not require an import library, this line is omitted.

The sixth line indicates whether an element exists as both a Unicode (W) version and an ANSI (A) version. If Unicode support is not available, this line is omitted.