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. |
PVOID TcPacketsBufferGetBuffer | ( | TC_PACKETS_BUFFER | buffer | ) |
It returns the underlying raw buffer of a packets buffer.
buffer | Handle to the packets buffer. |
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.
buffer | Handle to the packets buffer. |
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.
buffer | Handle to the packets buffer. |
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.
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. |
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.
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 // }
buffer | Handle to the packets buffer. |
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.
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. |
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.
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. |
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.
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. |
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.