Microsoft Internet Security and Acceleration Server 2000

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[]


[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.
[in] Length, in bytes, of the addresses pointed to by the ClientAddresses parameter.
[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.
[in] Length, in bytes, of the ProxyAddress parameter.
[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.

[in] Number of consecutive addresses to assign.
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.

[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.
[in] GUID identifying the protocol that the connection is part of. The GUID is the same GUID supplied to IFWXFilterAdmin::RegisterProtocolForFilter.
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.
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.
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.
[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

The method succeeded.
The protocol rules do not allow the user to use the protocol specified by the ProtocolGuid parameter.
The proxy address requested is already in use.
The specified address is not a valid address for this computer.


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 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