libparticle: packet: Functions for working with the packets (p_pkt_..., p_acl

int p_acl_add	(	struct p_packet *	pkt,
		const uint8_t *	type,
		const uint8_t *	data,
		size_t	len,
		int	may_frag
	)

Adds a new ACL-tuple to a CL-packet.

Adds an ACL-tuple to a CL-packet. The added ACL-tuple will be created by p_acl_add and stored at the end of the CL-packet.

Parameters:

	pkt	Pointer to the packet, where the ACL-tuple should be stored.
	type	ACL-type of the tuple that should be added to the packet. Must be 2 byte (3-to-2 coded).
	data	Data that should be stored in the ACL-tuple
	len	Length of data
	may_frag	If set to 1, this packet is allowed to be send fragmented. IMPORTANT: If set to 1, you can only add one single ACL-tuple to this packet and you only can send it with the frag-functions (send_addr and send_ack will initialize them automatically). Please set may_frag only to 1, if you really need it (large data in ACL-tuple), otherwise set it to 0.

Returns:: -1 on error, 0 otherwise

int p_acl_add_str	(	struct p_packet *	pkt,
		const char *	type_str,
		const uint8_t *	data,
		size_t	len,
		int	may_frag
	)

Adds a ACL-tuple to a CL-packet, ACL-type as string.

Adds an ACL-tuple to a CL-packet. The added ACL-tuple will be stored at the end of the CL-packet.

Parameters:

	pkt	Pointer to the packet, where the ACL-tuple should be stored.
	type_str	ACL-type of the tuple that should be added to the packet. Must be 3 characters
	data	Data which should be stored in the ACL-tuple
	len	Length of data
	may_frag	Reserved for future use with fragmentation. Should always be set to 0 at the moment.

Returns:: -1 on error, 0 otherwise

int p_acl_add_tuple	(	struct p_packet *	pkt,
		struct p_acl_tuple *	acl,
		int	may_frag
	)

Adds an existing ACL-tuple to a CL-packet.

Adds an existing ACL-tuple to a CL-packet. The added ACL-tuple will be stored at the end of the CL-packet.

Parameters:

	pkt	Pointer to the packet, where the ACL-tuple should be stored.
	acl	Pointer to the existing ACL-tuple, which should be appended to the packet.
	may_frag	If set to 1, this packet is allowed to be send fragmented.

Returns:: -1 on error, 0 otherwise

uint8_t p_acl_cmp	(	const struct p_acl_tuple *	first,
		const struct p_acl_tuple *	second
	)

compare two acl tuple for equality.

Two tuples are equal iff they contain the same data, have the same type and are part of the same packet.

Parameters:

	first	the first acl tuple.
	second	the second acl tuple.

Returns:: 0 if the tuple are not equal, 1 if they are

struct p_acl_tuple* p_acl_dup ( const struct p_acl_tuple * acl )

duplicate a acl tuple.

the duplicate holds the same data as the original tuple. Be sure to free

Parameters:

acl

the acl to duplicate

Returns:: NULL on error, a duplicate of the acl tuple.

int p_acl_findfirst	(	const struct p_packet *	packet,
		const uint8_t *	acl_type,
		struct p_acl_tuple **	found_tuple
	)

Find the first ACL-tuple in a packet by type.

Find the first ACL-tuple in a packet, where the ACL-type is the same as acl_type

Parameters:

	packet	Pointer to the packet, where the ACL-tuple should be found in.
	acl_type	Pointer to the ACL-type, which should be searched for. Must be coded with 3to2
	found_tuple	Pointer to the address, where the found ACL-tuple should be stored.

Returns:: Length of the found tuple on success, -1 on error.

int p_acl_findfirst_str	(	const struct p_packet *	packet,
		const char *	acl_type,
		struct p_acl_tuple **	found_tuple
	)

Find the first ACL-tuple in a packet by type, ACL-type as string.

Find the first ACL-tuple in a packet, where the ACL-type is the same as acl_type

Parameters:

	packet	Pointer to the packet, where the ACL-tuple should be found in.
	acl_type	Pointer to the ACL-type, which should be searched for. Must be 3 characters
	found_tuple	Pointer to the address, where the found ACL-tuple should be stored.

Returns:: Length of the found tuple on success, -1 on error.

int p_acl_findnext	(	const struct p_packet *	packet,
		struct p_acl_tuple *	current_tuple,
		struct p_acl_tuple **	found_tuple
	)

Find the next ACL-tuple in a packet by type.

Find the next ACL-tuple in a packet, where the ACL-type is the same as the ACL-type of the current ACL-tuple

Parameters:

	packet	Pointer to the packet, where the ACL-tuple should be found in.
	current_tuple	Pointer to the current ACL-tuple.
	found_tuple	Pointer to the address, where the found ACL-tuple should be stored.

Returns:: Length of the found tuple on success, -1 on error.

Throws exception EBADF when packet has no ACL-tuple. Please add an ACL-tuple and try again. Throws exception ETUPLENOTFOUND if searching for an ACL-tuple has ended without a result.

struct p_acl_tuple* p_acl_first ( const struct p_packet * packet )

Find the first ACL-tuple in a packet.

Parameters:

packet

Pointer to the packet, where the first ACL-tuple should be found in.

Returns:: Pointer to the first ACL-tuple in packet on success, NULL on error or if there isn't any ACL-tuple in packet

ssize_t p_acl_get_data	(	const struct p_acl_tuple *	acl,
		uint8_t **	data
	)

Get the data, which is stored in an ACL-tuple.

Parameters:

	acl	Pointer to the acl-tuple, where the data is stored in.
	data	data Pointer, which will be set to the data-field of acl

Returns:: Length of data on success, -1 on error.

ssize_t p_acl_get_len ( const struct p_acl_tuple * acl )

return the length of the data array in the acl tuple

Parameters:

acl

the acl tuple to get the length for

Returns:: the length of the data array in the acl tuple.

const uint8_t* p_acl_get_type ( const struct p_acl_tuple * acl )

Get the ACL-Type of an ACL-tuple.

Parameters:

acl

Pointer to the acl-tuple, where the type is stored in.

Returns:: Pointer to the ACL-type of acl on success, NULL on error.

char* p_acl_get_type_str	(	const struct p_acl_tuple *	acl,
		char *	buf
	)

Get the ACL-Type of an ACL-tuple as a string.

Parameters:

	acl	Pointer to the acl-tuple, where the type is stored in.
	buf	Pointer to a minimum 4-byte buffer, where the string will be stored in.

Returns:: char-pointer to the ACL-type of acl on success, NULL on error.

struct p_acl_tuple* p_acl_new	(	const uint8_t *	type,
		const uint8_t *	data,
		size_t	len
	)

Creates a new ACL-tuple.

Creates a new ACL-tuple

Parameters:

	type	ACL-type of the tuple that should be added to the packet. Must be 2 byte (3-to-2 coded).
	data	Data which should be stored in the ACL-tuple
	len	Length of data

Returns:: Pointer to the ACL-tuple on success, NULL on error.

struct p_acl_tuple* p_acl_new_str	(	const char *	type_str,
		const uint8_t *	data,
		size_t	len
	)

Creates a new ACL-tuple, ACL-type as string.

Creates a new ACL-tuple

Parameters:

	type_str	ACL-type of the tuple that should be added to the packet. Must be 3 characters
	data	Data which should be stored in the ACL-tuple
	len	Length of data

Returns:: Pointer to the ACL-tuple on success, NULL on error.

struct p_acl_tuple* p_acl_next	(	const struct p_packet *	packet,
		const struct p_acl_tuple *	acl_tuple
	)

Find the next ACL-tuple in a packet.

Find the next ACL-tuple in a packet after the current ACL-tuple

Parameters:

	packet	Pointer to the packet, where the next ACL-tuple should be found in.
	acl_tuple	Pointer to the current ACL-tuple

Returns:: Pointer to the next ACL-tuple in packet on success, NULL on error or if there are no more ACL-tuples in packet

void p_describe_pkt ( const struct p_packet * packet )

Prints out all information about a packet.

Debug function, which prints out all information of packet to stdout.

Parameters:

packet

Packet that should be described

struct p_packet* p_pkt_alloc ( void )

Create a new packet.

Creates a new (empty) Packet.

Returns:: Pointer to the new packet on success, -1 on error

struct p_packet* p_pkt_dup ( const struct p_packet * packet )

Duplicate a new packet.

Creates a new Packet from a given one.

Parameters:

packet

Pointer to the packet to be copied

Returns:: Pointer to the new packet on success, -1 on error

int p_pkt_free ( struct p_packet * packet )

Destroy a packet.

Destroys a packet and frees memory allocated for internal structures.

Parameters:

packet

Pointer to the packet

Returns:: 1 on success, -1 on error

int p_pkt_get_ack ( const struct p_packet * packet )

Get acknowledge-state from a packet.

Gets the acknowledge-state from a CL-packet.

Parameters:

packet

Pointer to the packet, from which the sequence-number should be get

Returns:: 1 if packet was already acknowledged, 0 if not, -1 on error.

const uint8_t* p_pkt_get_location ( const struct p_packet * packet )

Get location from a packet.

Gets the location-ID stored in a CL-packet. Output value will be a pointer to an array of integers.

Parameters:

packet

Pointer to the packet, from which the location-ID should be get

Returns:: Pointer to the location-ID from packet on success, NULL on error

char* p_pkt_get_location_str	(	const struct p_packet *	packet,
		char *	buffer,
		size_t	maxlen
	)

Get location-ID from a packet as string.

Gets the location-ID stored in a CL-packet. Output value will be a pointer to a "string" / array of characters

Parameters:

	packet	Pointer to the packet, from which the location-ID should be get
	buffer	Pointer to the buffer, where the location-ID should be stored
	maxlen	Size of the buffer

Returns:: Pointer to the location-ID from packet on success, NULL on error

char* p_pkt_get_payload	(	const struct p_packet *	pkt,
		char *	buf,
		size_t *	len
	)

Get the ACL-payload of pkt.

Parameters:

	pkt	Pointer to the packet
	buf	Pointer to a buffer, where the payload will be stored in.
	len	Pointer to the length of the buffer, contains actual size of return (use with buf=buf_len=0 to get payload size), 0 on failure

Returns:: char-pointer to the payload, null on failure

size_t p_pkt_get_payload_length ( struct p_packet * packet )

Get the total length of payload from a packet.

Gets the total length of payload from a packet

Parameters:

packet

Pointer to the packet, from which the payload size be get

Returns:: Size of payload from packet on success, -1 on error

uint8_t p_pkt_get_seq ( const struct p_packet * packet )

Get seq-# from a packet.

Gets the sequence-number from a CL-packet.

Parameters:

packet

Pointer to the packet, from which the sequence-number should be get

Returns:: Sequence-number from packet on success, -1 on error

const uint8_t* p_pkt_get_srcid ( const struct p_packet * packet )

Gets the source-ID stored in a CL-packet.

Parameters:

packet

Pointer to the packet, from which the source-ID should be get. Output value will be a pointer to an array of integers.

Returns:: Pointer to the source-ID from packet on success, NULL on error

char* p_pkt_get_srcid_str	(	const struct p_packet *	packet,
		char *	buffer,
		size_t	maxlen
	)

Get source-ID from a packet as string.

Gets the source-ID stored in a CL-packet. Output value will be a pointer to a "string" / array of characters

Parameters:

	packet	Pointer to the packet, from which the source-ID should be get
	buffer	Pointer to the buffer, where the source-ID should be stored
	maxlen	Size of the buffer

Returns:: Pointer to the source-ID from packet on success, NULL on error

int p_pkt_parse	(	struct p_packet *	packet,
		const char *	data,
		size_t	len
	)

Transforming a buffer into a packet.

Parses the data of a buffer (for example, after p_revc_raw) into the structure of a packet.

Parameters:

	packet	Pointer to the packet, where the parsed data should be stored
	data	Pointer to the buffer which should be parsed
	len	Size of buffer

Returns:: 0 on success, -1 on error

int p_pkt_set_location	(	struct p_packet *	packet,
		const uint8_t *	location
	)

Sets the location-ID of a CL-packet.

Parameters:

	packet	Pointer to the packet, where the location-ID should be set
	location	Pointer to the location-ID, which should be set at the packet. Must be a 44 byte array

Returns:: 1 on success, -1 on error

int p_pkt_set_location_str	(	struct p_packet *	packet,
		const char *	location
	)

Sets the location-ID of a CL-packet with a string.

Parameters:

	*packet	Pointer to the packet, where the location-ID should be set
	location	Pointer to the location-ID, which should be set at the packet. Must be a dotted string with 44 numbers between 0 and 255.

Returns:: 1 on success, -1 on error

int p_pkt_set_payload	(	struct p_packet *	pkt,
		const char *	data,
		size_t	len
	)

Set the ACL-payload of pkt.

Parameters:

	pkt	Pointer to the packet
	data	Pointer to a buffer containing the payload
	len	Pointer to the length of the payload

Returns:: -1 on failure, 0 otherwise

int p_pkt_set_seq	(	struct p_packet *	packet,
		const uint8_t	seq
	)

Sets the sequence-number of a CL-packet.

Please note: The flag PKT_INIT_SEQ will be reset after sending a packet. Second sending of the packet will be with the seq-ID from the socket. If you want to send a packet more than one time with a special seq-ID, you have to set it explicit before every sending!

Parameters:

	packet	Pointer to the packet, where the seq-number.
	seq	The sequence number you want to set to the packet.

Returns:: 0 on success, -1 on error

int p_pkt_set_srcid	(	struct p_packet *	packet,
		const uint8_t *	source
	)

Sets the source-ID of a CL-packet.

Parameters:

	packet	Pointer to the packet, where the source-ID should be set
	source	Pointer to the source-ID, which should be set at the packet. Must be a 8 byte array

Returns:: 1 on success, -1 on error

int p_pkt_set_srcid_str	(	struct p_packet *	packet,
		const char *	source
	)

Sets the source-ID of a CL-packet with a string.

Source must be a dotted string including either 8 or 4 numbers between 0 and 255. If source includes 8 numbers, the source ID will be set to exactly this source-ID. If source includes only 4 numbers, the source ID will be set to the ID "1.1.1.1.source".

Parameters:

	*packet	Pointer to the packet, where the location-ID should be set
	source	Pointer to the source-ID, which should be set at the packet.

Returns:: 1 on success, -1 on error

packet: Functions for working with the packets (p_pkt_..., p_acl_...)

Functions

Function Documentation


Functions
p_packet *	p_pkt_alloc (void)
	Create a new packet.
p_packet *	p_pkt_dup (const struct p_packet *packet)
	Duplicate a new packet.
int	p_pkt_free (struct p_packet *packet)
	Destroy a packet.
int	p_pkt_parse (struct p_packet packet, const char data, size_t len)
	Transforming a buffer into a packet.
const uint8_t *	p_pkt_get_location (const struct p_packet *packet)
	Get location from a packet.
const uint8_t *	p_pkt_get_srcid (const struct p_packet *packet)
	Gets the source-ID stored in a CL-packet.
uint8_t	p_pkt_get_seq (const struct p_packet *packet)
	Get seq-# from a packet.
int	p_pkt_get_ack (const struct p_packet *packet)
	Get acknowledge-state from a packet.
size_t	p_pkt_get_payload_length (struct p_packet *packet)
	Get the total length of payload from a packet.
char *	p_pkt_get_location_str (const struct p_packet packet, char buffer, size_t maxlen)
	Get location-ID from a packet as string.
char *	p_pkt_get_srcid_str (const struct p_packet packet, char buffer, size_t maxlen)
	Get source-ID from a packet as string.
int	p_pkt_set_location (struct p_packet packet, const uint8_t location)
	Sets the location-ID of a CL-packet.
int	p_pkt_set_srcid (struct p_packet packet, const uint8_t source)
	Sets the source-ID of a CL-packet.
int	p_pkt_set_seq (struct p_packet *packet, const uint8_t seq)
	Sets the sequence-number of a CL-packet.
int	p_pkt_set_location_str (struct p_packet packet, const char location)
	Sets the location-ID of a CL-packet with a string.
int	p_pkt_set_srcid_str (struct p_packet packet, const char source)
	Sets the source-ID of a CL-packet with a string.
void	p_describe_pkt (const struct p_packet *packet)
	Prints out all information about a packet.
char *	p_pkt_get_payload (const struct p_packet pkt, char buf, size_t *len)
	Get the ACL-payload of pkt.
int	p_pkt_set_payload (struct p_packet pkt, const char data, size_t len)
	Set the ACL-payload of pkt.
p_acl_tuple *	p_acl_first (const struct p_packet *packet)
	Find the first ACL-tuple in a packet.
p_acl_tuple *	p_acl_next (const struct p_packet packet, const struct p_acl_tuple acl_tuple)
	Find the next ACL-tuple in a packet.
int	p_acl_findfirst (const struct p_packet packet, const uint8_t acl_type, struct p_acl_tuple **found_tuple)
	Find the first ACL-tuple in a packet by type.
int	p_acl_findfirst_str (const struct p_packet packet, const char acl_type, struct p_acl_tuple **found_tuple)
	Find the first ACL-tuple in a packet by type, ACL-type as string.
int	p_acl_findnext (const struct p_packet packet, struct p_acl_tuple current_tuple, struct p_acl_tuple **found_tuple)
	Find the next ACL-tuple in a packet by type.
int	p_acl_add_tuple (struct p_packet pkt, struct p_acl_tuple acl, int may_frag)
	Adds an existing ACL-tuple to a CL-packet.
int	p_acl_add (struct p_packet pkt, const uint8_t type, const uint8_t *data, size_t len, int may_frag)
	Adds a new ACL-tuple to a CL-packet.
int	p_acl_add_str (struct p_packet pkt, const char type_str, const uint8_t *data, size_t len, int may_frag)
	Adds a ACL-tuple to a CL-packet, ACL-type as string.
p_acl_tuple *	p_acl_new (const uint8_t type, const uint8_t data, size_t len)
	Creates a new ACL-tuple.
p_acl_tuple *	p_acl_new_str (const char type_str, const uint8_t data, size_t len)
	Creates a new ACL-tuple, ACL-type as string.
ssize_t	p_acl_get_data (const struct p_acl_tuple acl, uint8_t *data)
	Get the data, which is stored in an ACL-tuple.
ssize_t	p_acl_get_len (const struct p_acl_tuple *acl)
	return the length of the data array in the acl tuple
const uint8_t *	p_acl_get_type (const struct p_acl_tuple *acl)
	Get the ACL-Type of an ACL-tuple.
char *	p_acl_get_type_str (const struct p_acl_tuple acl, char buf)
	Get the ACL-Type of an ACL-tuple as a string.
p_acl_tuple *	p_acl_dup (const struct p_acl_tuple *acl)
	duplicate a acl tuple.
uint8_t	p_acl_cmp (const struct p_acl_tuple first, const struct p_acl_tuple second)
	compare two acl tuple for equality.