IFWXIOBuffer Interface

The IFWXIOBuffer interface points to a reference counted memory buffer and provides the means of managing the buffer. The interface is a wrapper around a memory buffer. This allows the buffer to be used by many filters in a chain, avoiding the inefficient copying of buffers. For more information about memory buffers, see Buffer Objects.

The following rules apply to these buffers:

• The allocator of a buffer owns the buffer. Only the allocator may alter the contents of the buffer. This means that the receiver must not modify a buffer received in the IFWXIOCompletion::CompleteAsyncIO method after a call to the IFWXSocket::Recv method with the IOBuffer parameter set to NULL.
• A buffer that is sent (by way of the IFWXSocket::Send or IFWXSocket::SendTo method) must remain valid and unmodified until the reference count reaches zero. Even the owner of the buffer is not allowed to modify a buffer after it is sent.

The IFWXSocket::Send, IFWXSocket::SendTo, and IFWXSocket::Recv methods increment the reference count on the buffer. This reference count is maintained until the IFWXIOCompletion::CompleteAsyncIO method returns. You must call the Release method for each AddRef method that you called, and once more if you also created the buffer. Call AddRef if you keep a pointer to the buffer.

For more information about how the IFWXSocket interface is used in application filters, see Filter Object Model.

Syntax

interface IFWXIOBuffer : IUnknown

Methods

The IFWXIOBuffer interface inherits the methods of the IUnknown interface.

In addition, IFWXIOBuffer defines the following methods.

Method	Description
GetBufferAndSize	Gets the actual data from the memory buffer, and the actual size (not the allocated size) of the buffer.
SetDataSize	Sets the actual size of the memory buffer that was used.
Append	Appends a specified number of bytes of data to the buffer object.
ReadAt	Reads a specified number of bytes starting at a specified offset from the beginning of the buffer.
SendToBuffer	Copies a specified number of bytes starting at a specified offset from the beginning of the buffer to the given destination buffer.
GetBufferSizes	Gets the allocated and actual buffer sizes.

Remarks

Consider the size of the buffer needed. Data length information provided on the Internet may be inaccurate and may result in a buffer overflow.

This interface is generally implemented by the Microsoft Firewall service. You may want to implement IFWXIOBuffer in your filter if:

• You already have an allocated buffer that you want to send, and want to avoid creating a buffer copy. For example, the buffer was received from a remote procedure call (RPC) or an API that cannot work with the Firewall service buffers.
• You have to read into a preallocated buffer.
• You want to use your own allocator for the buffer.

You can rely on the Firewall service implementation of IFWXIOBuffer, and not code a filter implementation, if:

• You want to send a constant buffer.
• You want to send a section of another buffer.
• Your filter can handle or parse the data from IFWXIOBuffer
• Buffer copy is not of concern.

Requirements

Server	Requires Windows Server 2008.
Version	Requires Forefront Threat Management Gateway (TMG).
Header	Declared in Wspfwext.idl.

See Also

Filter Interfaces

Send comments about this topic to Microsoft

Build date: 11/30/2009