| Microsoft Internet Security and Acceleration Server 2000 |
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[] );
| Value | Description |
|---|---|
| FWX_PROTOCOL_TCP | The request is for a TCP socket. |
| FWX_PROTOCOL_UDP | The request is for a UDP socket. |
| 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. |
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.
IFWXConnection, IFWXIpFilter IFWXConnection::Kill, IFWXSession::BindForClient, IFWXConnection::SetClientAddress, IFWXSession::SetDataFilterFactory, IFWXFilterAdmin::RegisterProtocolForFilter