Packet

Types and functions for operating with bRAWcap packets. More...

Macros
#define	BRAWCAP_PACKET_SIZE_MAX   9018
	The maximum supported (byte) size for a single packet payload.
#define	BRAWCAP_PACKET_SIZE_MIN   14
	The minimum required (byte) size for a single packet payload.

Typedefs
typedef UINT16	brawcap_packet_size_t
	Type for handling the number of payload bytes per packet.
typedef struct _brawcap_packet	brawcap_packet_t
	bRAWcap packet object.

Functions
brawcap_status_t	brawcap_packet_create (brawcap_packet_t **const pPacket, const brawcap_packet_size_t maxSize)
	Creates a new packet.
brawcap_status_t	brawcap_packet_free (brawcap_packet_t *pPacket)
	Frees the specified packet. When this function is called the specified packet becomes invalid and it´s memory is released.
brawcap_status_t	brawcap_packet_status_get (brawcap_packet_t *const pPacket, brawcap_status_t *const pStatus)
	Reads out the status for the specified packet. The status will be set updated during reception/transmission. It indicates the status of the packet depending on the operation.
brawcap_status_t	brawcap_packet_timestamp_get (brawcap_packet_t *const pPacket, brawcap_timestamp_t **const pTimestamp)
	Reads out the timestamp object for the specified packet.
brawcap_status_t	brawcap_packet_length_on_wire_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLengthOnWire)
	Reads out the length on wire of the specified packet. This value is especially useful for received packets. It indicates the total packet payload byte size of the packet on wire. This may not equal to the captured payload byte size. Because the payload byte size depends on the configured filter and it´s bytes to capture parameters.
brawcap_status_t	brawcap_packet_payload_max_size_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pMaxPayloadSize)
	Reads out the max supported payload byte size of the specified packet. This value was set during packet creation (or buffer creation if it´s a buffered packet).
brawcap_status_t	brawcap_packet_payload_size_get (brawcap_packet_t *const pPacket, brawcap_packet_size_t *const pLength)
	Reads out the captured payload byte size of the specified packet. This indicates the total byte size of the (captured - if received) packet payload.
_BRAWCAP_DEPRECATED brawcap_status_t	brawcap_packet_payload_get (brawcap_packet_t *const pPacket, const char **const pPayload, brawcap_packet_size_t *const pLength)
	Reads out the payload of the specified packet.
brawcap_status_t	brawcap_packet_payload_get_v2 (brawcap_packet_t *const pPacket, const unsigned char **const pPayload, brawcap_packet_size_t *const pLength)
	Reads out the payload of the specified packet.
_BRAWCAP_DEPRECATED brawcap_status_t	brawcap_packet_payload_set (brawcap_packet_t *const pPacket, const char *const pPayload, const brawcap_packet_size_t length)
	Sets the packet payload of the specified packet.
brawcap_status_t	brawcap_packet_payload_set_v2 (brawcap_packet_t *const pPacket, const unsigned char *const pPayload, const brawcap_packet_size_t length)
	Sets the packet payload of the specified packet.

Detailed Description

Types and functions for operating with bRAWcap packets.

To create a packet use brawcap_packet_create. If a packet is not required anymore it shall be deleted with brawcap_packet_free.

Note

It is also possible to use "buffered" packets. Those packets must not be created and freed on their one. Instead they are part of a packet buffer. To access buffered packets use brawcap_buffer_at_index to get a packet on a specific position of the buffer or brawcap_buffer_iterator_eval on a packet buffer iterator. The second one is especially useful while iterating the buffer.

Attention

The user application shall never store buffered packets separately. Instead it should always request packets directly from the packet buffer and only use them as long as the packet buffer itself is valid.

List of examples:

1. Simple Packet Receiver
2. Buffered Receiver
3. Receive Timestamp Inspector

Macro Definition Documentation

BRAWCAP_PACKET_SIZE_MAX

#define BRAWCAP_PACKET_SIZE_MAX   9018

#include <brawcap_types_shared.h>

The maximum supported (byte) size for a single packet payload.

This value corresponds to jumbo frame size (9000 Bytes) + Ethernet header (14 Bytes) + single VLAN header (4 Bytes).

Examples

05_receive_simple_packet_receiver_f.c, 07_receive_buffered_receiver_f.c, 08_receive_timestamp_inspector_f.c, 10_transmit_buffered_transmitter_f.c, and 11_filter_bpf_f.c.

BRAWCAP_PACKET_SIZE_MIN

#define BRAWCAP_PACKET_SIZE_MIN   14

#include <brawcap_types_shared.h>

The minimum required (byte) size for a single packet payload.

This corresponds to Ethernet header size.

Note

The Ethernet standard defines a minimum packet length of 64 Bytes (including 4 Byte for Ethernet FCS). If smaller packets are sent the network adapter will automatically add some padding at the end of the payload. The padding contains zeros only and after the last padding/payload byte the Ethernet FCS will be added.

Typedef Documentation

brawcap_packet_size_t

typedef UINT16 brawcap_packet_size_t

#include <brawcap_types_shared.h>

Type for handling the number of payload bytes per packet.

Typically the packet payload size is set to the adapters max transmission unit (MTU) size + Ethernet header size and maybe a single VLAN header. Packet payload sizes have to be between BRAWCAP_PACKET_SIZE_MIN and BRAWCAP_PACKET_SIZE_MAX, values below/beyond are not accepted.

brawcap_packet_t

typedef struct _brawcap_packet brawcap_packet_t

#include <brawcap_types_shared.h>

bRAWcap packet object.

The packet object has to be used for each packet module function. Packet objects can be created and freed or retrieved from a packet buffer.

Function Documentation

brawcap_packet_create()

brawcap_status_t brawcap_packet_create	(	brawcap_packet_t **const	pPacket,
		const brawcap_packet_size_t	maxSize
	)

#include <brawcap.h>

Creates a new packet.

A packet can be used for receiving (single packet based) or transmitting (also single packet based).

If a packet is not required anymore it should be freed.

Parameters

[out]	pPacket	Will contain the new created packet, afterwards.
[in]	maxSize	The maximum supported byte size for the packet payload. This value cannot be changed after packet creation and determines how much memory is required for the packet. The packet can only contain payloads up to this value.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	Packet payload byte size to low/high.
BRAWCAP_STATUS_ERROR_FAILED	System error occurred (e.g. out of memory).

Examples

05_receive_simple_packet_receiver_f.c, 08_receive_timestamp_inspector_f.c, 10_transmit_buffered_transmitter_f.c, 11_filter_bpf_f.c, and 12_buffer_sorting_f.c.

brawcap_packet_free()

brawcap_status_t brawcap_packet_free

(

brawcap_packet_t *

pPacket

)

#include <brawcap.h>

Frees the specified packet. When this function is called the specified packet becomes invalid and it´s memory is released.

Warning

Freeing a packet is not thread safe and the user is responsible for synchronization.

Parameters

[in]

pPacket

The packet to be freed.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

05_receive_simple_packet_receiver_f.c, and 08_receive_timestamp_inspector_f.c.

brawcap_packet_status_get()

brawcap_status_t brawcap_packet_status_get	(	brawcap_packet_t *const	pPacket,
		brawcap_status_t *const	pStatus
	)

#include <brawcap.h>

Reads out the status for the specified packet. The status will be set updated during reception/transmission. It indicates the status of the packet depending on the operation.

Parameters

[in]	pPacket	The packet to read from.
[out]	pStatus	Will contain the packet status, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_packet_timestamp_get()

brawcap_status_t brawcap_packet_timestamp_get	(	brawcap_packet_t *const	pPacket,
		brawcap_timestamp_t **const	pTimestamp
	)

#include <brawcap.h>

Reads out the timestamp object for the specified packet.

Attention

The timestamp is part of the packet itself. Therefore the returned timestamp is only valid as long as the packet itself is valid. The user application shall not store the timestamp object separately and only used it as long as the packet is valid.

Parameters

[in]	pPacket	The packet to read from.
[out]	pTimestamp	Will contain the timestamp object of the packet, afterwards. This object can be used by the Timestamp module.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

05_receive_simple_packet_receiver_f.c, 08_receive_timestamp_inspector_f.c, 11_filter_bpf_f.c, and 12_buffer_sorting_f.c.

brawcap_packet_length_on_wire_get()

brawcap_status_t brawcap_packet_length_on_wire_get	(	brawcap_packet_t *const	pPacket,
		brawcap_packet_size_t *const	pLengthOnWire
	)

#include <brawcap.h>

Reads out the length on wire of the specified packet. This value is especially useful for received packets. It indicates the total packet payload byte size of the packet on wire. This may not equal to the captured payload byte size. Because the payload byte size depends on the configured filter and it´s bytes to capture parameters.

Parameters

[in]	pPacket	The packet to read from.
[out]	pLengthOnWire	Will contain the payload byte length on wire, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

05_receive_simple_packet_receiver_f.c, and 11_filter_bpf_f.c.

brawcap_packet_payload_max_size_get()

brawcap_status_t brawcap_packet_payload_max_size_get	(	brawcap_packet_t *const	pPacket,
		brawcap_packet_size_t *const	pMaxPayloadSize
	)

#include <brawcap.h>

Reads out the max supported payload byte size of the specified packet. This value was set during packet creation (or buffer creation if it´s a buffered packet).

Parameters

[in]	pPacket	The packet to read from.
[out]	pMaxPayloadSize	Will contain the max packet payload byte size, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_packet_payload_size_get()

brawcap_status_t brawcap_packet_payload_size_get	(	brawcap_packet_t *const	pPacket,
		brawcap_packet_size_t *const	pLength
	)

#include <brawcap.h>

Reads out the captured payload byte size of the specified packet. This indicates the total byte size of the (captured - if received) packet payload.

Parameters

[in]	pPacket	The packet to read from.
[out]	pLength	Will contain the captured payload byte size, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

07_receive_buffered_receiver_f.c.

brawcap_packet_payload_get()

_BRAWCAP_DEPRECATED brawcap_status_t brawcap_packet_payload_get	(	brawcap_packet_t *const	pPacket,
		const char **const	pPayload,
		brawcap_packet_size_t *const	pLength
	)

#include <brawcap.h>

Reads out the payload of the specified packet.

The function returns a pointer to the beginning of the packet payload.

Note

The returned payload pointer should be only accessed as long as the packet is not freed. If post processing is required a copy of the required payload should be done.

Attention

Accessing the packet payload is not thread safe and user is responsible for synchronization.

Byte order

The packet payload bytes are returned exactly as captured / constructed on the wire. For multi-byte protocol fields this means network byte order (big endian). No host <-> network endianness conversion is performed by bRAWcap. User code that interprets multi-byte integers must perform the appropriate conversion.

Deprecated:

Use brawcap_packet_payload_get_v2 instead.

Parameters

[in]	pPacket	The packet to read from.
[out]	pPayload	Will contain a pointer to the beginning of the packet payload, afterwards.
[out]	pLength	Will contain the total length of the packet payload, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

brawcap_packet_payload_get_v2()

brawcap_status_t brawcap_packet_payload_get_v2	(	brawcap_packet_t *const	pPacket,
		const unsigned char **const	pPayload,
		brawcap_packet_size_t *const	pLength
	)

#include <brawcap.h>

Reads out the payload of the specified packet.

The function returns a pointer to the beginning of the packet payload.

Note

The returned payload pointer should be only accessed as long as the packet is not freed. If post processing is required a copy of the required payload should be done.

Attention

Accessing the packet payload is not thread safe and user is responsible for synchronization.

Byte order

The payload reflects the exact on-the-wire representation (network order for multi-byte fields). bRAWcap does not transform endianness; callers parsing headers (e.g. IPv4, TCP) must convert multi-byte fields to host order where needed.

Parameters

[in]	pPacket	The packet to read from.
[out]	pPayload	Will contain a pointer to the beginning of the packet payload, afterwards.
[out]	pLength	Will contain the total length of the packet payload, afterwards.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.

Examples

05_receive_simple_packet_receiver_f.c, 11_filter_bpf_f.c, and 12_buffer_sorting_f.c.

brawcap_packet_payload_set()

_BRAWCAP_DEPRECATED brawcap_status_t brawcap_packet_payload_set	(	brawcap_packet_t *const	pPacket,
		const char *const	pPayload,
		const brawcap_packet_size_t	length
	)

#include <brawcap.h>

Sets the packet payload of the specified packet.

Note

It is not allowed to set a larger payload than the max byte payload size (specified during packet creation or buffer creation). If a larger payload is specified the function will fail and return an error.

Byte order

The provided pPayload buffer must already be in the desired on-the-wire layout. bRAWcap will transmit / store the bytes verbatim without performing any host-to-network conversions. For multi-byte protocol values you must encode them in network byte order (big endian) before calling this function.

Deprecated:

Use brawcap_packet_payload_set_v2 instead.

Parameters

[in]	pPacket	The packet to be modified.
[in]	pPayload	Pointer to the beginning of the payload to set.
[in]	length	Total byte size of the payload to set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	The specified payload size exceeds the packet max payload size.

brawcap_packet_payload_set_v2()

brawcap_status_t brawcap_packet_payload_set_v2	(	brawcap_packet_t *const	pPacket,
		const unsigned char *const	pPayload,
		const brawcap_packet_size_t	length
	)

#include <brawcap.h>

Sets the packet payload of the specified packet.

Note

It is not allowed to set a larger payload than the max byte payload size (specified during packet creation or buffer creation). If a larger payload is specified the function will fail and return an error.

Byte order

The payload is taken exactly as provided and treated as on-the-wire bytes. Caller code must ensure multi-byte protocol fields are encoded in network byte order (big endian) prior to calling.

Parameters

[in]	pPacket	The packet to be modified.
[in]	pPayload	Pointer to the beginning of the payload to set.
[in]	length	Total byte size of the payload to set.

Returns

Status	Description
BRAWCAP_STATUS_SUCCESS	Success.
BRAWCAP_STATUS_ERROR_INVALID_POINTER	At least one of the pointer parameters was invalid.
BRAWCAP_STATUS_ERROR_PARAM_OUT_OF_RANGE	The specified payload size exceeds the packet max payload size.

Examples

10_transmit_buffered_transmitter_f.c, and 12_buffer_sorting_f.c.