IFilterStreamSocketConnections Class Reference
[Stream Sockets, Filtering, Protected destructors on abstract base classes]

Inheritance diagram for IFilterStreamSocketConnections:

[legend]

List of all members.

---

Detailed Description

An interface for objects that wish to filter a byte stream. An instance of this interface can be added to a CStreamSocketConnectionManager as a filter by calling AddConnectionFilter(). Filters are called in order to process calls with requests being called from "top to bottom" and completions being called from "bottom to top". For example, if we call AddConnectionFilter() with filter A and then with filter B and then make a write request the data would be processed first by filter B and then by filter A (user -> B -> A -> wire). When a read completes the data is processed first by filter A and then by filter B (wire -> A -> B -> user). Each filter can manipulate the connection and data flow and may or may not pass calls onto filters below it in the chain. Thus a filter can swallow requests from layers above it by not passing them on and can also generate requests of its own. A filter is initialised once by the connection manager before it is used and during this initialisation it is given a management interface that can be used to generate new read and write events.

Public Types
enum	FilterProcessing { FilterContinueProcessing, FilterOperationComplete }
	Control how the filter chain is processed after this call completes. Each call to each filter will be passed a reference to this enum type and the reference is set to FilterContinueProcessing, if the filter wishes to 'swallow' the call then it should set the value to FilterOperationComplete and the call will not be passed any further down the chain. More...
Public Member Functions
virtual void	InitialiseFilter (IManageStreamSocketConnectionFilters &manager)=0
	Called once before any other method on this interface is called. The manager interface should be used to generate new read and write events.
virtual void	FilterSocketAttached (JetByteTools::Win32::IIndexedOpaqueUserData &userData)=0
	Called when a socket is first prepared for use. Can be used to allow the filter to plug its own user data into the socket's user data store. Note that unlike most other filter functions this call is always executed on the whole of the filter chain.
virtual void	FilterConnect (IFilterableStreamSocket &socket, const IFullAddress &address, const void *pUserData, const void *pFilterData, FilterProcessing &filterProcessing)=0
	Called before an outbound connection is attempted but after the socket is allocated. This call can be used to block or reroute connections or to "plug" connect data into the socket's user data.
virtual void	FilterConnectionEstablished (IFilterableStreamSocket &socket, const IAddress &address, FilterProcessing &filterProcessing)=0
	Called when a connection (inbound or outbound) is established. You can determine which direction the connection is (if that's important) by calling GetConnectionDirection() on the socket. Note that a filter may receive a read or write request before a connection establishment notification if a filter lower in the chain issues a read or write during its connection establishment notification.
virtual void	FilterConnectionFailed (IFilterableStreamSocket &socket, const IAddress &address, const DWORD lastError)=0
	Called when an outbound connection faile to be established. The filter cannot block these notifications, but it can use it to track the success of connects that it is filtering.
virtual void	FilterReadRequest (IFilterableStreamSocket &socket, JetByteTools::IO::IBuffer *pBuffer, FilterProcessing &filterProcessing)=0
	Called when a read is requested. The buffer is optional, if no buffer is passed with the call then one will be allocated just before the read is issued. Filters can prevent the application (and filters above) from issuing reads by simply not passing these calls on to the next filter in the chain. If a filter wishes to generate its own reads then it should use IManageStreamSocketConnectionFilters rather than calling this function with its own buffers.
virtual void	FilterReadCompleted (IFilterableStreamSocket &socket, JetByteTools::IO::IBuffer &buffer, FilterProcessing &filterProcessing)=0
	Called when a read has completed. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing read completions and also generating their own read completions via the IManageStreamSocketConnectionFilters interface.
virtual void	FilterReadCompletionError (IFilterableStreamSocket &socket, JetByteTools::IO::IBuffer &buffer, const DWORD lastError, FilterProcessing &filterProcessing)=0
	Called when a read has completed with an error. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing read completions and also generating their own read completions via the IManageStreamSocketConnectionFilters interface. Note that fiddling around with completion errors is probably unwise...
virtual void	FilterWriteRequest (IFilterableStreamSocket &socket, JetByteTools::IO::IBuffer &buffer, FilterProcessing &filterProcessing)=0
	Called when a write is requested. Filters can prevent the application (and filters above) from issuing reads by simply not passing these calls on to the next filter in the chain. If a filter wishes to generate its own reads then it should use IManageStreamSocketConnectionFilters rather than calling this function with its own buffers.
virtual void	FilterWriteCompleted (IFilterableStreamSocket &socket, JetByteTools::IO::IBuffer &buffer, FilterProcessing &filterProcessing)=0
	Called when a write has completed. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing write completions and also generating their own write completions via the IManageStreamSocketConnectionFilters interface.
virtual void	FilterWriteCompletionError (IFilterableStreamSocket &socket, JetByteTools::IO::IBuffer &buffer, const DWORD lastError, FilterProcessing &filterProcessing)=0
	Called when a write has completed with an error. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing write completions and also generating their own write completions via the IManageStreamSocketConnectionFilters interface. Note that fiddling around with completion errors is probably unwise...
virtual void	FilterClientClose (IFilterableStreamSocket &socket, FilterProcessing &filterProcessing)=0
	Called when the receive side of a connection is closed by the peer.
virtual void	FilterConnectionReset (IFilterableStreamSocket &socket, const DWORD lastError, FilterProcessing &filterProcessing)=0
	Called when the a connection is reset.
virtual void	FilterConnectionClosed (IFilterableStreamSocket &socket, FilterProcessing &filterProcessing)=0
	Called when the connection is closed.
virtual void	FilterSocketReleased (JetByteTools::Win32::IIndexedOpaqueUserData &userData)=0
	Called after IStreamSocketConnectionManagerCallback::OnSocketReleased() callback and before the socket is passed to the allocator. This can be used to remove any user data that was added by the filter in a FilterConnect() call or a FilterSocketAttached() call. Note that unlike most other filter functions this call is always executed on the whole of the filter chain.
Protected Member Functions
	~IFilterStreamSocketConnections ()
	We never delete instances of this interface; you must manage the lifetime of the class that implements it.

---

Member Enumeration Documentation

enum FilterProcessing

Control how the filter chain is processed after this call completes. Each call to each filter will be passed a reference to this enum type and the reference is set to FilterContinueProcessing, if the filter wishes to 'swallow' the call then it should set the value to FilterOperationComplete and the call will not be passed any further down the chain.

Enumerator:

FilterContinueProcessing
FilterOperationComplete

---

Constructor & Destructor Documentation

~IFilterStreamSocketConnections

(

)

[inline, protected]

We never delete instances of this interface; you must manage the lifetime of the class that implements it.

---

Member Function Documentation

virtual void InitialiseFilter

(

IManageStreamSocketConnectionFilters &

manager

)

[pure virtual]

Called once before any other method on this interface is called. The manager interface should be used to generate new read and write events.

Implemented in CNullStreamSocketConnectionFilter, and CTelnetProtocolStreamSocketConnectionFilter.

virtual void FilterSocketAttached

(

JetByteTools::Win32::IIndexedOpaqueUserData &

userData

)

[pure virtual]

Called when a socket is first prepared for use. Can be used to allow the filter to plug its own user data into the socket's user data store. Note that unlike most other filter functions this call is always executed on the whole of the filter chain.

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterConnect	(	IFilterableStreamSocket &	socket,
		const IFullAddress &	address,
		const void *	pUserData,
		const void *	pFilterData,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called before an outbound connection is attempted but after the socket is allocated. This call can be used to block or reroute connections or to "plug" connect data into the socket's user data.

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterConnectionEstablished	(	IFilterableStreamSocket &	socket,
		const IAddress &	address,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when a connection (inbound or outbound) is established. You can determine which direction the connection is (if that's important) by calling GetConnectionDirection() on the socket. Note that a filter may receive a read or write request before a connection establishment notification if a filter lower in the chain issues a read or write during its connection establishment notification.

Implemented in CNullStreamSocketConnectionFilter, and CTelnetProtocolStreamSocketConnectionFilter.

virtual void FilterConnectionFailed	(	IFilterableStreamSocket &	socket,
		const IAddress &	address,
		const DWORD	lastError
	)			[pure virtual]

Called when an outbound connection faile to be established. The filter cannot block these notifications, but it can use it to track the success of connects that it is filtering.

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterReadRequest	(	IFilterableStreamSocket &	socket,
		JetByteTools::IO::IBuffer *	pBuffer,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when a read is requested. The buffer is optional, if no buffer is passed with the call then one will be allocated just before the read is issued. Filters can prevent the application (and filters above) from issuing reads by simply not passing these calls on to the next filter in the chain. If a filter wishes to generate its own reads then it should use IManageStreamSocketConnectionFilters rather than calling this function with its own buffers.

Implemented in CNullStreamSocketConnectionFilter, and CTelnetProtocolStreamSocketConnectionFilter.

virtual void FilterReadCompleted	(	IFilterableStreamSocket &	socket,
		JetByteTools::IO::IBuffer &	buffer,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when a read has completed. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing read completions and also generating their own read completions via the IManageStreamSocketConnectionFilters interface.

Implemented in CNullStreamSocketConnectionFilter, and CTelnetProtocolStreamSocketConnectionFilter.

virtual void FilterReadCompletionError	(	IFilterableStreamSocket &	socket,
		JetByteTools::IO::IBuffer &	buffer,
		const DWORD	lastError,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when a read has completed with an error. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing read completions and also generating their own read completions via the IManageStreamSocketConnectionFilters interface. Note that fiddling around with completion errors is probably unwise...

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterWriteRequest	(	IFilterableStreamSocket &	socket,
		JetByteTools::IO::IBuffer &	buffer,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when a write is requested. Filters can prevent the application (and filters above) from issuing reads by simply not passing these calls on to the next filter in the chain. If a filter wishes to generate its own reads then it should use IManageStreamSocketConnectionFilters rather than calling this function with its own buffers.

Implemented in CNullStreamSocketConnectionFilter, and CTelnetProtocolStreamSocketConnectionFilter.

virtual void FilterWriteCompleted	(	IFilterableStreamSocket &	socket,
		JetByteTools::IO::IBuffer &	buffer,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when a write has completed. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing write completions and also generating their own write completions via the IManageStreamSocketConnectionFilters interface.

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterWriteCompletionError	(	IFilterableStreamSocket &	socket,
		JetByteTools::IO::IBuffer &	buffer,
		const DWORD	lastError,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when a write has completed with an error. The filter can manipulate the data in any way that they like, this includes using the data for their own purposes and swallowing write completions and also generating their own write completions via the IManageStreamSocketConnectionFilters interface. Note that fiddling around with completion errors is probably unwise...

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterClientClose	(	IFilterableStreamSocket &	socket,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when the receive side of a connection is closed by the peer.

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterConnectionReset	(	IFilterableStreamSocket &	socket,
		const DWORD	lastError,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when the a connection is reset.

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterConnectionClosed	(	IFilterableStreamSocket &	socket,
		FilterProcessing &	filterProcessing
	)			[pure virtual]

Called when the connection is closed.

Implemented in CNullStreamSocketConnectionFilter.

virtual void FilterSocketReleased

(

JetByteTools::Win32::IIndexedOpaqueUserData &

userData

)

[pure virtual]

Called after IStreamSocketConnectionManagerCallback::OnSocketReleased() callback and before the socket is passed to the allocator. This can be used to remove any user data that was added by the filter in a FilterConnect() call or a FilterSocketAttached() call. Note that unlike most other filter functions this call is always executed on the whole of the filter chain.

Implemented in CNullStreamSocketConnectionFilter, and CTelnetProtocolStreamSocketConnectionFilter.

---