The C++ framework for developing highly scalable, high performance servers on Windows platforms.

• Home
• What
• Why
• How
• Who
• Products
• Pricing
• Blog
• Contact

Search

IFilterDatagramSocketConnections Class Reference
[Datagram Sockets, Filtering, Protected destructors on abstract base classes]

Inheritance diagram for IFilterDatagramSocketConnections:

[legend]

List of all members.

---

Detailed Description

An interface for objects that wish to filter datagrams. An instance of this interface can be added to a CDatagramSocketConnectionManager 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 contents of the datagram 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 Member Functions
virtual void	InitialiseFilter (IManageDatagramSocketConnectionFilters &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::Core::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 (IFilterableDatagramSocket &socket, const IFullAddress &address, const void *pUserData, const void *pFilterData)=0
	Called when a datagram connection manager issues a call to 'Connect' on a datagram socket. Note that this only means that the socket is logically connected and allows for Read and Write operations to occur with an implicit peer address of the address supplied to the call to Connect.
virtual void	FilterConnectionEstablished (IFilterableDatagramSocket &socket, const IAddress &address)=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 (IFilterableDatagramSocket &socket, const IAddress &address, DWORD lastError)=0
	Called when an outbound connection fails 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 bool	FilterReadRequest (IFilterableDatagramSocket &socket, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a read is requested. The supplied buffer is optional and may be null. The filter can remove the supplied buffer or add one of its own. If no buffer is available and the read is allowed to occur then a buffer will be allocated just before the read is issued. Filters can prevent the application (and filters above) from issuing reads by returning false which will cause the filter chain traversal to stop and the request to be cancelled. If a filter wishes to generate its own reads then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer.
virtual void	FilterReadCompleted (IFilterableDatagramSocket &socket, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a read has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own read completions via the IManageDatagramSocketConnectionFilters interface.
virtual void	FilterReadCompletionError (IFilterableDatagramSocket &socket, JetByteTools::IO::CSmartBuffer &buffer, DWORD lastError)=0
	Called when a read has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.
virtual bool	FilterRecvFromRequest (IFilterableDatagramSocket &socket, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a RecvFrom is requested. The supplied buffer is optional and may be null. The filter can remove the supplied buffer or add one of its own. If no buffer is available and the read is allowed to occur then a buffer will be allocated just before the read is issued. Filters can prevent the application (and filters above) from issuing reads by returning false which will cause the filter chain traversal to stop and the request to be cancelled. If a filter wishes to generate its own reads then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer.
virtual void	FilterRecvFromCompleted (IFilterableDatagramSocket &socket, const IAddress &address, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a RecvFrom has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own read completions via the IManageDatagramSocketConnectionFilters interface.
virtual void	FilterRecvFromCompletionError (IFilterableDatagramSocket &socket, const IAddress &address, JetByteTools::IO::CSmartBuffer &buffer, DWORD lastError)=0
	Called when a read has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.
virtual void	FilterWriteRequest (IFilterableDatagramSocket &socket, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a write is requested. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. If a filter wishes to generate its own writes then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer. Note that should a filter clear the CSmartBuffer then it is taking responsibility for calling WriteCompleted() on the socket when the write actually completes. This may be straight away, if the filter is simply preventing writes being issued or it may be when the buffer is eventually written if it's queuing writes internally.
virtual void	FilterWriteCompleted (IFilterableDatagramSocket &socket, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a write has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own write completions via the IManageDatagramSocketConnectionFilters interface.
virtual void	FilterWriteCompletionError (IFilterableDatagramSocket &socket, JetByteTools::IO::CSmartBuffer &buffer, DWORD lastError)=0
	Called when a write has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.
virtual void	FilterSendToRequest (IFilterableDatagramSocket &socket, const IAddress &address, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a SendTo is requested. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. If a filter wishes to generate its own SendTos then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer. Note that should a filter clear the CSmartBuffer then it is taking responsibility for calling WriteCompleted() on the socket when the SendTo actually completes. This may be straight away, if the filter is simply preventing SendTos being issued or it may be when the buffer is eventually written if it's queuing writes internally.
virtual void	FilterSendToCompleted (IFilterableDatagramSocket &socket, const IAddress &address, JetByteTools::IO::CSmartBuffer &buffer)=0
	Called when a SendTo has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own write completions via the IManageDatagramSocketConnectionFilters interface.
virtual void	FilterSendToCompletionError (IFilterableDatagramSocket &socket, const IAddress &address, JetByteTools::IO::CSmartBuffer &buffer, DWORD lastError)=0
	Called when a SendTo has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.
virtual void	FilterConnectionReset (IFilterableDatagramSocket &socket, DWORD lastError)=0
	Called when the a connection is reset.
virtual void	FilterConnectionClosure (IFilterableDatagramSocket &socket, ConnectionClosureReason reason)=0
	Called when the connection is closed.
virtual void	FilterConnectionClosed (IFilterableDatagramSocket &socket)=0
virtual void	FilterSocketReleased (JetByteTools::Core::IIndexedOpaqueUserData &userData)=0
	Called after IDatagramSocketConnectionManagerCallback::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
virtual	~IFilterDatagramSocketConnections ()
	We never delete instances of this interface; you must manage the lifetime of the class that implements it.

---

Constructor & Destructor Documentation

virtual ~IFilterDatagramSocketConnections

(

)

[protected, virtual]

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

---

Member Function Documentation

virtual void InitialiseFilter

(

IManageDatagramSocketConnectionFilters &

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

virtual void FilterSocketAttached

(

JetByteTools::Core::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 CNullDatagramSocketConnectionFilter.

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

Called when a datagram connection manager issues a call to 'Connect' on a datagram socket. Note that this only means that the socket is logically connected and allows for Read and Write operations to occur with an implicit peer address of the address supplied to the call to Connect.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterConnectionEstablished	(	IFilterableDatagramSocket &	socket,
		const IAddress &	address
	)			[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 CNullDatagramSocketConnectionFilter.

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

Called when an outbound connection fails 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 CNullDatagramSocketConnectionFilter.

virtual bool FilterReadRequest	(	IFilterableDatagramSocket &	socket,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a read is requested. The supplied buffer is optional and may be null. The filter can remove the supplied buffer or add one of its own. If no buffer is available and the read is allowed to occur then a buffer will be allocated just before the read is issued. Filters can prevent the application (and filters above) from issuing reads by returning false which will cause the filter chain traversal to stop and the request to be cancelled. If a filter wishes to generate its own reads then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterReadCompleted	(	IFilterableDatagramSocket &	socket,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a read has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own read completions via the IManageDatagramSocketConnectionFilters interface.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterReadCompletionError	(	IFilterableDatagramSocket &	socket,
		JetByteTools::IO::CSmartBuffer &	buffer,
		DWORD	lastError
	)			[pure virtual]

Called when a read has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.

Implemented in CNullDatagramSocketConnectionFilter.

virtual bool FilterRecvFromRequest	(	IFilterableDatagramSocket &	socket,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a RecvFrom is requested. The supplied buffer is optional and may be null. The filter can remove the supplied buffer or add one of its own. If no buffer is available and the read is allowed to occur then a buffer will be allocated just before the read is issued. Filters can prevent the application (and filters above) from issuing reads by returning false which will cause the filter chain traversal to stop and the request to be cancelled. If a filter wishes to generate its own reads then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterRecvFromCompleted	(	IFilterableDatagramSocket &	socket,
		const IAddress &	address,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a RecvFrom has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own read completions via the IManageDatagramSocketConnectionFilters interface.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterRecvFromCompletionError	(	IFilterableDatagramSocket &	socket,
		const IAddress &	address,
		JetByteTools::IO::CSmartBuffer &	buffer,
		DWORD	lastError
	)			[pure virtual]

Called when a read has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterWriteRequest	(	IFilterableDatagramSocket &	socket,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a write is requested. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. If a filter wishes to generate its own writes then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer. Note that should a filter clear the CSmartBuffer then it is taking responsibility for calling WriteCompleted() on the socket when the write actually completes. This may be straight away, if the filter is simply preventing writes being issued or it may be when the buffer is eventually written if it's queuing writes internally.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterWriteCompleted	(	IFilterableDatagramSocket &	socket,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a write has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own write completions via the IManageDatagramSocketConnectionFilters interface.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterWriteCompletionError	(	IFilterableDatagramSocket &	socket,
		JetByteTools::IO::CSmartBuffer &	buffer,
		DWORD	lastError
	)			[pure virtual]

Called when a write has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterSendToRequest	(	IFilterableDatagramSocket &	socket,
		const IAddress &	address,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a SendTo is requested. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. If a filter wishes to generate its own SendTos then it should use IManageDatagramSocketConnectionFilters rather than calling this function with its own buffer. Note that should a filter clear the CSmartBuffer then it is taking responsibility for calling WriteCompleted() on the socket when the SendTo actually completes. This may be straight away, if the filter is simply preventing SendTos being issued or it may be when the buffer is eventually written if it's queuing writes internally.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterSendToCompleted	(	IFilterableDatagramSocket &	socket,
		const IAddress &	address,
		JetByteTools::IO::CSmartBuffer &	buffer
	)			[pure virtual]

Called when a SendTo has completed. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop. Filters can also generate any number of their own write completions via the IManageDatagramSocketConnectionFilters interface.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterSendToCompletionError	(	IFilterableDatagramSocket &	socket,
		const IAddress &	address,
		JetByteTools::IO::CSmartBuffer &	buffer,
		DWORD	lastError
	)			[pure virtual]

Called when a SendTo has completed with an error. The filter can manipulate the data in any way that it likes. This includes using the data for its own purposes, replacing the data with its own, either by replacing the buffer with a completely new buffer or by replacing the contents of the supplied buffer, and cancelling the call by clearing the CSmartBuffer (by calling Release()) which will cause the filter chain traversal to stop.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterConnectionReset	(	IFilterableDatagramSocket &	socket,
		DWORD	lastError
	)			[pure virtual]

Called when the a connection is reset.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterConnectionClosure	(	IFilterableDatagramSocket &	socket,
		ConnectionClosureReason	reason
	)			[pure virtual]

Called when the connection is closed.

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterConnectionClosed

(

IFilterableDatagramSocket &

socket

)

[pure virtual]

Implemented in CNullDatagramSocketConnectionFilter.

virtual void FilterSocketReleased

(

JetByteTools::Core::IIndexedOpaqueUserData &

userData

)

[pure virtual]

Called after IDatagramSocketConnectionManagerCallback::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 CNullDatagramSocketConnectionFilter.

---