IFWXConnection Interface

The IFWXConnection interface represents a particular connection and provides methods that are specific to it.

For more information about how the IFWXConnection interface is used in application filters, see Filter Object Model.

Syntax

interface IFWXConnection : IUnknown

Methods

The IFWXConnection interface inherits the methods of the IUnknown interface.

In addition, IFWXConnection defines the following methods.

Method Description

AttachDataFilter

Attaches a data filter to the connection.

AttachDataFilterWithDestination

Attaches a data filter to the connection. The data filter is associated with a remote UDP destination.

EmulateConnection

Creates a connection to a client for a filter-emulated listening (inbound) connection.

EmulateForBind

Emulates a bind for an incoming request.

EmulateForConnect

Emulates a connection for an outbound request. In the outbound scenario, a data filter emulates the external connection for an internal client.

IncrementBytesSentCounter

Updates the counter with how many bytes have been sent over an emulated connection.

SetSocketName

sets the name of the socket for the connection. Call this method only if the caller is emulating the connection.

Kill

Forces the connection to terminate.

GetExternalSocketName

Gets the socket name for the external socket. This method is implemented by calling the Winsock getsockname function on the actual external socket.

SetClientAddress

Gives the client address for a connection returned by the IFWXSession::BindForClient method, for which the client address was not previously specified.

Deny

Denies the current operation on the connection object.

SetBufferSize

Sets the buffer size for a connection.

GetExternalPeerName

Gets the peer name for the external socket. This method is implemented by calling the Windows Sockets (Winsock)getpeername function on the actual external socket.

GetSession

Returns the session object to which a connection belongs.

SetIpFilter

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.

GetIpFilter

Gets a copy of the IP filter object for the connection.

GetConnectionFlags

Retrieves the flags that are set for the connection.

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.

When a registered event occurs, the Microsoft Firewall service will call IFWXSessionFilter::FirewallEventHandler and will pass the FirewallEvent parameter to it. Included in the FirewallEvent parameter is a pointer to the IFWXConnection.

After the pointer is available, you can use the IFWXConnection methods, such as IFWXConnection::AttachDataFilter.

The IFWXConnection methods are understood most easily in the context of connection scenarios:

Scenario A: Bind and 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 the connection. In the case of a bind request, this applies to UDP only.

Scenario B: Bind and 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 an event of type fwx_AcceptedConnection 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.

Note  A single TCP connection between a listening socket on the Firewall service and an external server may result in the creation of two ss: a listening connection on the Firewall service, and an inbound connection. 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

Server Requires Windows Server 2008.
Version Requires Forefront Threat Management Gateway (TMG).
Header

Declared in Wspfwext.idl.

See Also

Filter Interfaces


Send comments about this topic to Microsoft

Build date: 11/30/2009

 

© 2008 Microsoft Corporation. All rights reserved.