Packets buffer related functions

Functions

PVOID TcPacketsBufferGetBuffer (TC_PACKETS_BUFFER buffer)
 It returns the underlying raw buffer of a packets buffer.
ULONG TcPacketsBufferGetEffectiveLength (TC_PACKETS_BUFFER buffer)
 It returns the effective length of a packets buffer i.e. the number of bytes that have been effectively used for packets in the internal raw buffer.
ULONG TcPacketsBufferGetLength (TC_PACKETS_BUFFER buffer)
 It returns the total length of a packets buffer i.e. the size of the internal raw buffer.
TC_STATUS TcPacketsBufferCreate (ULONG size, PTC_PACKETS_BUFFER pBuffer)
 It creates a packets buffer used for transmission given its internal raw buffer size.
VOID TcPacketsBufferDestroy (TC_PACKETS_BUFFER buffer)
 It releases a buffer previously allocated by TcPacketsBufferCreate or returned by TcInstanceReceivePackets.
VOID TcPacketsBufferResetIndex (TC_PACKETS_BUFFER buffer)
 It resets the internal index used to read packets with TcPacketsBufferQueryNextPacket to the beginning of the buffer.
TC_STATUS TcPacketsBufferQueryNextPacket (TC_PACKETS_BUFFER buffer, PTC_PACKET_HEADER pHeader, PVOID *ppData)
 It returns the next available packet within a packets buffer.
TC_STATUS TcPacketsBufferCommitNextPacket (TC_PACKETS_BUFFER buffer, PTC_PACKET_HEADER pHeader, PVOID pData)
 It adds a packet to a given packets buffer.
TC_STATUS TcPacketsBufferSetEffectiveLength (TC_PACKETS_BUFFER buffer, ULONG effectiveLength)
 It sets the effective length of the buffer i.e. the number of bytes that actually contain packets in the internal raw buffer.

Function Documentation

PVOID TcPacketsBufferGetBuffer ( TC_PACKETS_BUFFER  buffer  ) 

It returns the underlying raw buffer of a packets buffer.

Parameters:
buffer Handle to the packets buffer.
Returns:
A pointer to the underlying raw buffer. Use TcPacketsBufferGetLength to obtain the length of such buffer.
Note:
In the current version of the TurboCap API, it's not possible to access the raw buffer of a packets buffer received from an aggregating instance, i.e. when capturing from a BAP or TcAP port. In this case the return value is a NULL pointer.

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.

ULONG TcPacketsBufferGetEffectiveLength ( TC_PACKETS_BUFFER  buffer  ) 

It returns the effective length of a packets buffer i.e. the number of bytes that have been effectively used for packets in the internal raw buffer.

During reception, the effective length is the number of bytes in the internal raw buffer that actually contain packets. The total length of the buffer (as obtained by TcPacketsBufferGetLength) is always greater or equal to the effective length.

During transmission, the effective length is the number of bytes in the internal raw buffer that need to be transmitted. The total length of the buffer (as obtained by TcPacketsBufferGetLength) is always greater or equal to the effective length.

Parameters:
buffer Handle to the packets buffer.
Returns:
The effective length of the underlying raw buffer. Use TcPacketsBufferGetLength to obtain the total length of such buffer.
Note:
In the current version of the TurboCap API, it's not possible to access the raw buffer of a packets buffer received from an aggregating instance, i.e. when capturing from a BAP or TcAP port. In this case the return value is 0.

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.

ULONG TcPacketsBufferGetLength ( TC_PACKETS_BUFFER  buffer  ) 

It returns the total length of a packets buffer i.e. the size of the internal raw buffer.

Parameters:
buffer Handle to the packets buffer.
Returns:
The total length of the underlying raw buffer. Use TcPacketsBufferGetEffectiveLength to obtain the effective length of such buffer i.e. the number of bytes that are actually in use.
Note:
In the current version of the TurboCap API, it's not possible to access the raw buffer of a packets buffer received from an aggregating instance, i.e. when capturing from a BAP or TcAP port. In this case the return value is 0.

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.

TC_STATUS TcPacketsBufferCreate ( ULONG  size,
PTC_PACKETS_BUFFER  pBuffer 
)

It creates a packets buffer used for transmission given its internal raw buffer size.

Parameters:
size Size of the internal raw buffer, in bytes.
pBuffer Pointer to a caller allocated packets buffer handle. On success it will contain a valid packets buffer handle.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

VOID TcPacketsBufferDestroy ( TC_PACKETS_BUFFER  buffer  ) 

It releases a buffer previously allocated by TcPacketsBufferCreate or returned by TcInstanceReceivePackets.

Parameters:
buffer Handle to the packets buffer to destroy.

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.
Also, please see the Thread Safety note in TcInstanceReceivePackets regarding how to destroy the packets buffers returned by that function.

VOID TcPacketsBufferResetIndex ( TC_PACKETS_BUFFER  buffer  ) 

It resets the internal index used to read packets with TcPacketsBufferQueryNextPacket to the beginning of the buffer.

Each packets buffer maintains an internal index used to read packets with TcPacketsBufferQueryNextPacket. This counter is automatically reset to the first packet in a packets buffer when a packets buffer is created or when the packets buffer is returned by TcInstanceReceivePackets. This function should be used when the packets within a packets buffer should be scanned multiple times, as in the code snippet below

    while(TcPacketsBufferQueryNextPacket(packetsBuffer, &header, &data) == TC_SUCCESS)
    {
        //
        // process packet
        //
    }
    
    //
    // reset the index
    //
    TcPacketsBufferResetIndex(packetsBuffer);

    //
    // scan the packets again
    //
    while(TcPacketsBufferQueryNextPacket(packetsBuffer, &header, &data) == TC_SUCCESS)
    {
        //
        // process packet 2nd time
        //
    }
Parameters:
buffer Handle to the packets buffer.
Note:
In the current version of the TurboCap API, it's not possible to reset the buffer index of a packets buffer received from an aggregating instance, i.e. when capturing from a BAP or TcAP port.

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.

TC_STATUS TcPacketsBufferQueryNextPacket ( TC_PACKETS_BUFFER  buffer,
PTC_PACKET_HEADER  pHeader,
PVOID *  ppData 
)

It returns the next available packet within a packets buffer.

Each packets buffer maintains an internal index used to read packets. This function returns the next available packet (i.e. the one pointed to by the internal read index) and updates the internal read index. If the end of the packets buffer has been reached, the function returns TC_ERROR_END_OF_BUFFER.

Parameters:
buffer Handle to the packets buffer.
pHeader Pointer to a caller allocated TC_PACKET_HEADER. On success it will contain the header of the packet.
ppData Pointer to a a caller allocated VOID pointer. On success, it will point to the packet, starting from the Ethernet header. The returned packet must not be freed. The packet remains valid until the packets buffer itself is valid.
Returns:

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.

TC_STATUS TcPacketsBufferCommitNextPacket ( TC_PACKETS_BUFFER  buffer,
PTC_PACKET_HEADER  pHeader,
PVOID  pData 
)

It adds a packet to a given packets buffer.

The packet and the header passed as parameters are copied in the internal buffer used to hold the packets. The effective buffer length of the buffer (i.e. the number of bytes used in the internal buffer), as returned by TcPacketsBufferGetEffectiveLength is updated on success. In case the free bytes in the internal buffer (Length - EffectiveLength) are not enough to hold the packet, the function fails with error code TC_ERROR_BUFFER_FULL.

Parameters:
buffer Handle to the packets buffer.
pHeader Pointer to the header describing the packet to be added to the packets buffer.
pData Pointer to the buffer containing the packet itself, starting from the Ethernet header.
Returns:
Note:
  • The packet buffer passed as parameter (pData) can be freed after a call to this function. This function makes a internal copy of the packet data.
  • It's not possible to add packets to a packets buffer received from an aggregating port (BAP or TcAP port).

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.

TC_STATUS TcPacketsBufferSetEffectiveLength ( TC_PACKETS_BUFFER  buffer,
ULONG  effectiveLength 
)

It sets the effective length of the buffer i.e. the number of bytes that actually contain packets in the internal raw buffer.

Parameters:
buffer Handle to the packets buffer.
effectiveLength Length of the bytes effectively in use in the internal buffer. This number must be less or equal to the maximum buffer size as returned by TcPacketsBufferGetLength.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe if called on different packets buffer handles (TC_PACKETS_BUFFER). Calling this function on the same packets buffer from concurrent threads must be synchronized.


TurboCap API documentation. Copyright (c) 2007-2008 CACE Technologies. All rights reserved.