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