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 |
---|---|
Gets the actual data from the memory buffer, and the actual size (not the allocated size) of the buffer. |
|
Sets the actual size of the memory buffer that was used. |
|
Appends a specified number of bytes of data to the buffer object. |
|
Reads a specified number of bytes starting at a specified offset from the beginning of the buffer. |
|
Copies a specified number of bytes starting at a specified offset from the beginning of the buffer to the given destination buffer. |
|
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 R2 or Windows Server 2008 x64 Edition with SP2. |
Version | Requires Forefront Threat Management Gateway (TMG) 2010. |
Header | Declared in Wspfwext.idl. |
See Also
Send comments about this topic to Microsoft
Build date: 6/30/2010