Base class for classes representing DHCP messages. More...

#include <pkt.h>

Inheritance diagram for isc::dhcp::Pkt:

Public Member Functions
virtual	~Pkt ()
	Virtual destructor.

void	addClass (const isc::dhcp::ClientClass &client_class, bool required=false)
	Adds a specified class to the packet.

virtual void	addOption (const OptionPtr &opt)
	Adds an option to this packet.

void	addPktEvent (const std::string &label, const boost::posix_time::ptime &timestamp=PktEvent::now())
	Adds an event to the end of the event stack.

void	addPktEvent (const std::string &label, const struct timeval &timestamp)
	Adds an event to the end of the event stack with the timestamp specified as a struct timeval.

void	addSubClass (const isc::dhcp::ClientClass &class_def, const isc::dhcp::ClientClass &subclass)
	Adds a specified subclass to the packet.

void	clearPktEvents ()
	Discards contents of the packet event stack.

OptionCollection	cloneOptions ()
	Clones all options so that they can be safely modified.

bool	delOption (uint16_t type)
	Attempts to delete first suboption of requested type.

std::string	dumpPktEvents (bool verbose=false) const
	Creates a dump of the stack contents to a string for logging.

isc::util::OutputBuffer &	getBuffer ()
	Returns reference to output buffer.

const ClientClasses &	getClasses (bool required=false) const
	Returns the class set.

std::string	getIface () const
	Returns interface name.

int	getIndex () const
	Returns interface index.

virtual std::string	getLabel () const
	Returns text representation primary packet identifiers.

const isc::asiolink::IOAddress &	getLocalAddr () const
	Returns local IP address.

uint16_t	getLocalPort () const
	Returns local UDP (and soon TCP) port.

HWAddrPtr	getMAC (uint32_t hw_addr_src)
	Returns MAC address.

virtual const char *	getName () const =0
	Returns name of the DHCP message.

OptionPtr	getOption (const uint16_t type)
	Returns the first option of specified type.

isc::dhcp::OptionCollection	getOptions (const uint16_t type)
	Returns all instances of specified type.

const std::list< PktEvent > &	getPktEvents ()
	Fetches the current event stack contents.

boost::posix_time::ptime	getPktEventTime (const std::string &label) const
	Fetches the timestamp for a given event in the stack.

const isc::asiolink::IOAddress &	getRemoteAddr () const
	Returns remote IP address.

HWAddrPtr	getRemoteHWAddr () const
	Returns the remote HW address obtained from raw sockets.

uint16_t	getRemotePort () const
	Returns remote port.

const SubClassRelationContainer &	getSubClassesRelations () const
	Returns the class set including template classes associated with subclasses.

const boost::posix_time::ptime &	getTimestamp () const
	Returns packet timestamp.

uint32_t	getTransid () const
	Returns value of transaction-id field.

virtual uint8_t	getType () const =0
	Returns message type (e.g.

bool	inClass (const isc::dhcp::ClientClass &client_class)
	Checks whether a client belongs to a given class.

bool	indexSet () const
	Checks if interface index has been set.

bool	isCopyRetrievedOptions () const
	Returns whether the copying of retrieved options is enabled.

virtual size_t	len ()=0
	Returns packet size in binary format.

virtual void	pack ()=0
	Prepares on-wire format of DHCP (either v4 or v6) packet.

void	repack ()
	Copies content of input buffer to output buffer.

void	resetIndex ()
	Resets interface index to negative value.

virtual void	setCopyRetrievedOptions (const bool copy)
	Controls whether the option retrieved by the Pkt::getOption should be copied before being returned.

void	setIface (const std::string &iface)
	Sets interface name.

void	setIndex (const unsigned int ifindex)
	Sets interface index.

void	setLocalAddr (const isc::asiolink::IOAddress &local)
	Sets local IP address.

void	setLocalPort (uint16_t local)
	Sets local UDP (and soon TCP) port.

void	setPktEvent (const std::string &label, const boost::posix_time::ptime &timestamp=PktEvent::now())
	Updates (or adds) an event in the event stack.

void	setRemoteAddr (const isc::asiolink::IOAddress &remote)
	Sets remote IP address.

void	setRemoteHWAddr (const HWAddrPtr &hw_addr)
	Sets remote hardware address.

void	setRemoteHWAddr (const uint8_t htype, const uint8_t hlen, const std::vector< uint8_t > &hw_addr)
	Sets remote hardware address.

void	setRemotePort (uint16_t remote)
	Sets remote UDP (and soon TCP) port.

void	setTimestamp (boost::posix_time::ptime &timestamp)
	Set socket receive timestamp.

void	setTransid (uint32_t transid)
	Sets transaction-id value.

virtual void	setType (uint8_t type)=0
	Sets message type (e.g.

virtual std::string	toText () const =0
	Returns text representation of the packet.

virtual void	unpack ()=0
	Parses on-wire form of DHCP (either v4 or v6) packet.

void	updateTimestamp ()
	Update packet timestamp.

Public Member Functions inherited from isc::hooks::CalloutHandleAssociate
	CalloutHandleAssociate ()
	Constructor.

CalloutHandlePtr	getCalloutHandle ()
	Returns callout handle.

void	resetCalloutHandle ()
	Reset callout handle.

Public Attributes
ClientClasses	classes_
	Classes this packet belongs to.

OptionBuffer	data_
	Unparsed data (in received packets).

isc::dhcp::OptionCollection	options_
	Collection of options present in this message.

ClientClasses	required_classes_
	Classes which are required to be evaluated.

SubClassRelationContainer	subclasses_
	SubClasses this packet belongs to.

Protected Member Functions
	Pkt (const uint8_t *buf, uint32_t len, const isc::asiolink::IOAddress &local_addr, const isc::asiolink::IOAddress &remote_addr, uint16_t local_port, uint16_t remote_port)
	Constructor.

	Pkt (uint32_t transid, const isc::asiolink::IOAddress &local_addr, const isc::asiolink::IOAddress &remote_addr, uint16_t local_port, uint16_t remote_port)
	Constructor.

virtual HWAddrPtr	getMACFromDocsisCMTS ()=0
	Attempts to extract MAC/Hardware address from DOCSIS options inserted by the CMTS (the relay agent)

virtual HWAddrPtr	getMACFromDocsisModem ()=0
	Attempts to extract MAC/Hardware address from DOCSIS options inserted by the modem itself.

virtual HWAddrPtr	getMACFromDUID ()=0
	Attempts to obtain MAC address from DUID-LL or DUID-LLT.

HWAddrPtr	getMACFromIPv6 (const isc::asiolink::IOAddress &addr)
	Attempts to convert IPv6 address into MAC.

virtual HWAddrPtr	getMACFromIPv6RelayOpt ()=0
	Attempts to obtain MAC address from relay option client-linklayer-addr.

virtual HWAddrPtr	getMACFromRemoteIdRelayOption ()=0
	Attempts to obtain MAC address from remote-id relay option.

virtual HWAddrPtr	getMACFromSrcLinkLocalAddr ()=0
	Attempts to obtain MAC address from source link-local IPv6 address.

OptionPtr	getNonCopiedOption (const uint16_t type) const
	Returns the first option of specified type without copying.

OptionCollection	getNonCopiedOptions (const uint16_t opt_type) const
	Returns all option instances of specified type without copying.

Protected Attributes
isc::util::OutputBuffer	buffer_out_
	Output buffer (used during message transmission)

bool	copy_retrieved_options_
	Indicates if a copy of the retrieved option should be returned when Pkt::getOption is called.

std::string	iface_
	Name of the network interface the packet was received/to be sent over.

unsigned int	ifindex_
	Interface index.

isc::asiolink::IOAddress	local_addr_
	Local IP (v4 or v6) address.

uint16_t	local_port_
	local TDP or UDP port

isc::asiolink::IOAddress	remote_addr_
	Remote IP address.

HWAddrPtr	remote_hwaddr_

uint16_t	remote_port_
	remote TCP or UDP port

boost::posix_time::ptime	timestamp_
	packet timestamp

uint32_t	transid_
	Transaction-id (32 bits for v4, 24 bits for v6)

Protected Attributes inherited from isc::hooks::CalloutHandleAssociate
CalloutHandlePtr	callout_handle_
	Callout handle stored.

Detailed Description

Base class for classes representing DHCP messages.

This is a base class that holds common information (e.g. source and destination ports) and operations (e.g. add, get, delete options) for derived classes representing both DHCPv4 and DHCPv6 messages. The Pkt4 and Pkt6 classes derive from it.

Note: This is abstract class. Please instantiate derived classes such as Pkt4 or Pkt6.

Definition at line 161 of file pkt.h.

Constructor & Destructor Documentation

◆ Pkt() [1/2]

isc::dhcp::Pkt::Pkt	(	uint32_t	transid,
		const isc::asiolink::IOAddress &	local_addr,
		const isc::asiolink::IOAddress &	remote_addr,
		uint16_t	local_port,
		uint16_t	remote_port )

protected

Constructor.

This constructor is typically used for transmitted messages as it creates an empty (no options) packet. The constructor is protected, so only derived classes can call it. Pkt class cannot be instantiated anyway, because it is an abstract class.

Parameters

transid	transaction-id
local_addr	local IPv4 or IPv6 address
remote_addr	remote IPv4 or IPv6 address
local_port	local UDP (one day also TCP) port
remote_port	remote UDP (one day also TCP) port

Definition at line 24 of file pkt.cc.

◆ Pkt() [2/2]

isc::dhcp::Pkt::Pkt	(	const uint8_t *	buf,
		uint32_t	len,
		const isc::asiolink::IOAddress &	local_addr,
		const isc::asiolink::IOAddress &	remote_addr,
		uint16_t	local_port,
		uint16_t	remote_port )

protected

Constructor.

This constructor is typically used for received messages as it takes a buffer that's going to be parsed as one of arguments. The constructor is protected, so only derived classes can call it. Pkt class cannot be instantiated anyway, because it is an abstract class.

Parameters

buf	pointer to a buffer that contains on-wire data
len	length of the pointer specified in buf
local_addr	local IPv4 or IPv6 address
remote_addr	remote IPv4 or IPv6 address
local_port	local UDP (one day also TCP) port
remote_port	remote UDP (one day also TCP) port

Definition at line 32 of file pkt.cc.

References data_, isc_throw, and len().

Here is the call graph for this function:

◆ ~Pkt()

virtual isc::dhcp::Pkt::~Pkt ( )

inlinevirtual

Virtual destructor.

There is nothing to clean up here, but since there are virtual methods, we define virtual destructor to ensure that derived classes will have a virtual one, too.

Definition at line 761 of file pkt.h.

Member Function Documentation

◆ addClass()

void isc::dhcp::Pkt::addClass	(	const isc::dhcp::ClientClass &	client_class,
		bool	required = false )

Adds a specified class to the packet.

A class can be added to the same packet repeatedly. Any additional attempts to add to a packet the class already added, will be ignored silently.

Parameters

client_class	name of the class to be added
required	the class is marked for required evaluation

Definition at line 126 of file pkt.cc.

References classes_, isc::dhcp::ClientClasses::insert(), required_classes_, and subclasses_.

Here is the call graph for this function:

◆ addOption()

void isc::dhcp::Pkt::addOption ( const OptionPtr & opt )

virtual

Adds an option to this packet.

Derived classes may provide more specialized implementations. In particular Pkt4 provides one that checks if option is unique.

Parameters

opt	option to be added.

Reimplemented in isc::dhcp::Pkt4.

Definition at line 57 of file pkt.cc.

References options_.

Referenced by isc::dhcp::Pkt4::addOption().

◆ addPktEvent() [1/2]

void isc::dhcp::Pkt::addPktEvent	(	const std::string &	label,
		const boost::posix_time::ptime &	timestamp = PktEvent::now() )

Adds an event to the end of the event stack.

Parameters

label	string identifying the event
timestamp	time at which the event occurred. It is expected to be in UTC/microseconds. Defaults to the current time.

Definition at line 321 of file pkt.cc.

Referenced by addPktEvent().

◆ addPktEvent() [2/2]

void isc::dhcp::Pkt::addPktEvent	(	const std::string &	label,
		const struct timeval &	timestamp )

Adds an event to the end of the event stack with the timestamp specified as a struct timeval.

Parameters

label	string identifying the event
timestamp	time at which the event occurred. It is expected to be in UTC/microseconds.

Definition at line 338 of file pkt.cc.

References addPktEvent().

Here is the call graph for this function:

◆ addSubClass()

void isc::dhcp::Pkt::addSubClass	(	const isc::dhcp::ClientClass &	class_def,
		const isc::dhcp::ClientClass &	subclass )

Adds a specified subclass to the packet.

A subclass can be added to the same packet repeatedly. Any additional attempts to add to a packet the subclass already added, will be ignored silently.

Parameters

class_def	name of the class definition to be added
subclass	name of the subclass to be added

Definition at line 135 of file pkt.cc.

References classes_, isc::dhcp::ClientClasses::contains(), isc::dhcp::ClientClasses::insert(), and subclasses_.

Here is the call graph for this function:

◆ clearPktEvents()

void isc::dhcp::Pkt::clearPktEvents ( )

Discards contents of the packet event stack.

This is provided primarily for test purposes.

Definition at line 358 of file pkt.cc.

◆ cloneOptions()

OptionCollection isc::dhcp::Pkt::cloneOptions ( )

Clones all options so that they can be safely modified.

Returns: A container with option clones.

Definition at line 48 of file pkt.cc.

References options_.

◆ delOption()

bool isc::dhcp::Pkt::delOption ( uint16_t type )

Attempts to delete first suboption of requested type.

If there are several options of the same type present, only the first option will be deleted.

Parameters

type	Type of option to be deleted.

Returns: true if option was deleted, false if no such option existed

Definition at line 110 of file pkt.cc.

References options_.

◆ dumpPktEvents()

std::string isc::dhcp::Pkt::dumpPktEvents ( bool verbose = false ) const

Creates a dump of the stack contents to a string for logging.

Parameters

verbose when true the dump is more verbose, includes durations between events and spans multiple lines. Defaults to false.

Definition at line 363 of file pkt.cc.

◆ getBuffer()

isc::util::OutputBuffer & isc::dhcp::Pkt::getBuffer ( )

inline

Returns reference to output buffer.

Returned buffer will contain reasonable data only for output (TX) packet and after pack() was called.

RX packet or TX packet before pack() will return buffer with zero length. This buffer is returned as non-const, so hooks framework (and user's callouts) can modify them if needed

Note: This buffer is only valid till object that returned it exists.

Returns: reference to output buffer

Definition at line 245 of file pkt.h.

References buffer_out_.

Referenced by isc::dhcp::Pkt4o6::pack().

◆ getClasses()

const ClientClasses & isc::dhcp::Pkt::getClasses ( bool required = false ) const

inline

Returns the class set.

Note: This should be used only to iterate over the class set.

Parameters

required return classes or required to be evaluated classes.

Returns: if required is false (the default) the classes the packet belongs to else the classes which are required to be evaluated.

Definition at line 380 of file pkt.h.

References classes_, and required_classes_.

◆ getIface()

std::string isc::dhcp::Pkt::getIface ( ) const

inline

Returns interface name.

Returns interface name over which packet was received or is going to be transmitted.

Returns: interface name

Definition at line 682 of file pkt.h.

References iface_.

◆ getIndex()

int isc::dhcp::Pkt::getIndex ( ) const

inline

Returns interface index.

Returns: interface index

Definition at line 665 of file pkt.h.

References ifindex_.

◆ getLabel()

virtual std::string isc::dhcp::Pkt::getLabel ( ) const

inlinevirtual

Returns text representation primary packet identifiers.

This method is intended to be used to provide as a consistent way to identify packets within log statements. Derivations should supply there own implementation.

Returns: string with text representation

Reimplemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Definition at line 275 of file pkt.h.

References isc_throw.

◆ getLocalAddr()

const isc::asiolink::IOAddress & isc::dhcp::Pkt::getLocalAddr ( ) const

inline

Returns local IP address.

Returns: local address

Definition at line 609 of file pkt.h.

References local_addr_.

◆ getLocalPort()

uint16_t isc::dhcp::Pkt::getLocalPort ( ) const

inline

Returns local UDP (and soon TCP) port.

This sets a local port, i.e. destination port for recently received packet or a source port for to be transmitted packet.

Returns: local port

Definition at line 629 of file pkt.h.

References local_port_.

◆ getMAC()

HWAddrPtr isc::dhcp::Pkt::getMAC ( uint32_t hw_addr_src )

Returns MAC address.

The difference between this method and getRemoteHWAddr() is that getRemoteHWAddr() returns only what was obtained from raw sockets. This method is more generic and can attempt to obtain MAC from varied sources: raw sockets, client-id, link-local IPv6 address, and various relay options.

Note: Technically the proper term for this information is a link layer address, but it is frequently referred to MAC or hardware address. Since we're calling the feature "MAC addresses in DHCPv6", we decided to keep the name of getMAC().

hw_addr_src takes a combination of bit values specified in HWADDR_SOURCE_* constants.

Parameters

hw_addr_src a bitmask that specifies hardware address source

Todo: : Implement an array of method pointers instead of set of ifs

Definition at line 180 of file pkt.cc.

References getMACFromDocsisCMTS(), getMACFromDocsisModem(), getMACFromDUID(), getMACFromIPv6RelayOpt(), getMACFromRemoteIdRelayOption(), getMACFromSrcLinkLocalAddr(), getRemoteHWAddr(), isc::dhcp::HWAddr::HWADDR_SOURCE_CLIENT_ADDR_RELAY_OPTION, isc::dhcp::HWAddr::HWADDR_SOURCE_DOCSIS_CMTS, isc::dhcp::HWAddr::HWADDR_SOURCE_DOCSIS_MODEM, isc::dhcp::HWAddr::HWADDR_SOURCE_DUID, isc::dhcp::HWAddr::HWADDR_SOURCE_IPV6_LINK_LOCAL, isc::dhcp::HWAddr::HWADDR_SOURCE_RAW, and isc::dhcp::HWAddr::HWADDR_SOURCE_REMOTE_ID.

Here is the call graph for this function:

◆ getMACFromDocsisCMTS()

virtual HWAddrPtr isc::dhcp::Pkt::getMACFromDocsisCMTS ( )

protectedpure virtual

Attempts to extract MAC/Hardware address from DOCSIS options inserted by the CMTS (the relay agent)

This is a generic mechanism for extracting hardware address from the DOCSIS options.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt6 class have respective implementation. This method is currently not implemented in DHCPv4.

Returns: hardware address (if necessary DOCSIS suboptions are present)

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Referenced by getMAC().

◆ getMACFromDocsisModem()

virtual HWAddrPtr isc::dhcp::Pkt::getMACFromDocsisModem ( )

protectedpure virtual

Attempts to extract MAC/Hardware address from DOCSIS options inserted by the modem itself.

This is a generic mechanism for extracting hardware address from the DOCSIS options.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt6 class have respective implementation. This method is currently not implemented in DHCPv4.

Returns: hardware address (if necessary DOCSIS suboptions are present)

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Referenced by getMAC().

◆ getMACFromDUID()

virtual HWAddrPtr isc::dhcp::Pkt::getMACFromDUID ( )

protectedpure virtual

Attempts to obtain MAC address from DUID-LL or DUID-LLT.

This method is called from getMAC(HWADDR_SOURCE_DUID) and should not be called directly. It will attempt to extract MAC address information from DUID if its type is LLT or LL. If this method fails, it will return NULL.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt6 class have respective implementation. This method is not applicable to DHCPv4.

Returns: hardware address (or NULL)

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Referenced by getMAC().

◆ getMACFromIPv6()

HWAddrPtr isc::dhcp::Pkt::getMACFromIPv6 ( const isc::asiolink::IOAddress & addr )

protected

Attempts to convert IPv6 address into MAC.

Utility method that attempts to convert link-local IPv6 address to the MAC address. That works only for link-local IPv6 addresses that are based on EUI-64.

Note: This method uses hardware type of the interface the packet was received on. If you have multiple access technologies in your network (e.g. client connected to WiFi that relayed the traffic to the server over Ethernet), hardware type may be invalid.

Parameters

addr	IPv6 address to be converted

Returns: hardware address (or NULL)

Definition at line 277 of file pkt.cc.

References isc::dhcp::HWAddr::HWADDR_SOURCE_IPV6_LINK_LOCAL, iface_, isc::dhcp::IfaceMgr::instance(), isc::asiolink::IOAddress::isV6LinkLocal(), and isc::asiolink::IOAddress::toBytes().

Referenced by isc::dhcp::Pkt6::getMACFromSrcLinkLocalAddr().

Here is the call graph for this function:

◆ getMACFromIPv6RelayOpt()

virtual HWAddrPtr isc::dhcp::Pkt::getMACFromIPv6RelayOpt ( )

protectedpure virtual

Attempts to obtain MAC address from relay option client-linklayer-addr.

This method is called from getMAC(HWADDR_SOURCE_CLIENT_ADDR_RELAY_OPTION) and should not be called directly. It will extract the client's MAC/Hardware address from option client_linklayer_addr (RFC6939) inserted by the relay agent closest to the client. If this method fails, it will return NULL.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt6 class have respective implementation. This method is not applicable to DHCPv4.

Returns: hardware address (or NULL)

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Referenced by getMAC().

◆ getMACFromRemoteIdRelayOption()

virtual HWAddrPtr isc::dhcp::Pkt::getMACFromRemoteIdRelayOption ( )

protectedpure virtual

Attempts to obtain MAC address from remote-id relay option.

This method is called from getMAC(HWADDR_SOURCE_REMOTE_ID) and should not be called directly. It will attempt to extract MAC address information from remote-id option inserted by a relay agent closest to the client. If this method fails, it will return NULL.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt6 class have respective implementation. This method is not applicable to DHCPv4.

Returns: hardware address (or NULL)

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Referenced by getMAC().

◆ getMACFromSrcLinkLocalAddr()

virtual HWAddrPtr isc::dhcp::Pkt::getMACFromSrcLinkLocalAddr ( )

protectedpure virtual

Attempts to obtain MAC address from source link-local IPv6 address.

This method is called from getMAC(HWADDR_SOURCE_IPV6_LINK_LOCAL) and should not be called directly. It is not 100% reliable. The source IPv6 address does not necessarily have to be link-local (may be global or ULA) and even if it's link-local, it doesn't necessarily be based on EUI-64. For example, Windows supports RFC4941, which randomized IID part of the link-local address. If this method fails, it will return NULL.

For direct message, it attempts to use remote_addr_ field. For relayed message, it uses peer-addr of the first relay.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt6 class have respective implementation. This method is not applicable to DHCPv4.

Returns: hardware address (or NULL)

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Referenced by getMAC().

◆ getName()

virtual const char * isc::dhcp::Pkt::getName ( ) const

pure virtual

Returns name of the DHCP message.

For all unsupported messages the derived classes must return "UNKNOWN".

Returns: Pointer to "const" string containing DHCP message name. The implementations in the derived classes should statically allocate returned strings and the caller must not release the returned pointer.

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

◆ getNonCopiedOption()

OptionPtr isc::dhcp::Pkt::getNonCopiedOption ( const uint16_t type ) const

protected

Returns the first option of specified type without copying.

This method is internally used by the Pkt class and derived classes to retrieve a pointer to the specified option. This method doesn't copy the option before returning it to the caller.

Parameters

type	Option type.

Returns: Pointer to the option of specified type or NULL pointer if such option is not present.

Definition at line 62 of file pkt.cc.

References options_.

Referenced by isc::dhcp::Pkt4::addOption(), isc::dhcp::Pkt6::getClientId(), isc::dhcp::Pkt4::getLabel(), isc::dhcp::Pkt6::getMACFromDUID(), isc::dhcp::Pkt4::getType(), and isc::dhcp::Pkt4::setType().

◆ getNonCopiedOptions()

OptionCollection isc::dhcp::Pkt::getNonCopiedOptions ( const uint16_t opt_type ) const

protected

Returns all option instances of specified type without copying.

This is a variant of getOptions method, which returns a collection of options without copying them. This method should be only used by the Pkt6 class and derived classes. Any external callers should use getOptions which copies option instances before returning them when the Pkt::copy_retrieved_options_ flag is set to true.

Parameters

opt_type Option code.

Returns: Collection of options found.

Definition at line 84 of file pkt.cc.

References options_.

Referenced by isc::dhcp::Pkt6::getMACFromDocsisModem().

◆ getOption()

OptionPtr isc::dhcp::Pkt::getOption ( const uint16_t type )

Returns the first option of specified type.

Returns the first option of specified type. Note that in DHCPv6 several instances of the same option are allowed (and frequently used).

The options will be only returned after unpack() is called.

Parameters

type	option type we are looking for

Returns: pointer to found option (or NULL)

Definition at line 71 of file pkt.cc.

References copy_retrieved_options_, and options_.

◆ getOptions()

OptionCollection isc::dhcp::Pkt::getOptions ( const uint16_t type )

Returns all instances of specified type.

Returns all instances of options of the specified type. DHCPv6 protocol allows (and uses frequently) multiple instances.

Parameters

type	option type we are looking for

Returns: instance of option collection with requested options

Definition at line 91 of file pkt.cc.

References copy_retrieved_options_, and options_.

◆ getPktEvents()

const std::list< PktEvent > & isc::dhcp::Pkt::getPktEvents ( )

inline

Fetches the current event stack contents.

Returns: reference to the list of events.

Definition at line 567 of file pkt.h.

◆ getPktEventTime()

ptime isc::dhcp::Pkt::getPktEventTime ( const std::string & label ) const

Fetches the timestamp for a given event in the stack.

Parameters

label string identifying the event

Returns: timestamp of the event (UTC/microseconds)

Definition at line 347 of file pkt.cc.

References isc::dhcp::PktEvent::EMPTY_TIME().

Here is the call graph for this function:

◆ getRemoteAddr()

const isc::asiolink::IOAddress & isc::dhcp::Pkt::getRemoteAddr ( ) const

inline

Returns remote IP address.

Returns: remote address

Definition at line 595 of file pkt.h.

References remote_addr_.

◆ getRemoteHWAddr()

HWAddrPtr isc::dhcp::Pkt::getRemoteHWAddr ( ) const

inline

Returns the remote HW address obtained from raw sockets.

Returns: remote HW address.

Definition at line 733 of file pkt.h.

References remote_hwaddr_.

Referenced by getMAC().

◆ getRemotePort()

uint16_t isc::dhcp::Pkt::getRemotePort ( ) const

inline

Returns remote port.

Returns: remote port

Definition at line 646 of file pkt.h.

References remote_port_.

◆ getSubClassesRelations()

const SubClassRelationContainer & isc::dhcp::Pkt::getSubClassesRelations ( ) const

inline

Returns the class set including template classes associated with subclasses.

Note: This should be used only to iterate over the class set.; SubClasses are always last.

Returns: if required is false (the default) the classes the packet belongs to else the classes which are required to be evaluated.

Definition at line 392 of file pkt.h.

References subclasses_.

◆ getTimestamp()

const boost::posix_time::ptime & isc::dhcp::Pkt::getTimestamp ( ) const

inline

Returns packet timestamp.

Returns packet timestamp value updated when packet is received or send.

Returns: packet timestamp.

Definition at line 514 of file pkt.h.

References timestamp_.

◆ getTransid()

uint32_t isc::dhcp::Pkt::getTransid ( ) const

inline

Returns value of transaction-id field.

Returns: transaction-id

Definition at line 341 of file pkt.h.

References transid_.

Referenced by isc::dhcp::Pkt6::getLabel(), isc::perfdhcp::PerfPkt4::rawPack(), isc::perfdhcp::PerfPkt6::rawPack(), isc::perfdhcp::PerfPkt4::rawUnpack(), and isc::perfdhcp::PerfPkt6::rawUnpack().

◆ getType()

virtual uint8_t isc::dhcp::Pkt::getType ( ) const

pure virtual

Returns message type (e.g.

1 = SOLICIT).

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt4 and Pkt6 class have respective implementations of this method.

Returns: message type

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

◆ inClass()

bool isc::dhcp::Pkt::inClass ( const isc::dhcp::ClientClass & client_class )

Checks whether a client belongs to a given class.

Parameters

client_class name of the class

Returns: true if belongs

Definition at line 121 of file pkt.cc.

References classes_, and isc::dhcp::ClientClasses::contains().

Here is the call graph for this function:

◆ indexSet()

bool isc::dhcp::Pkt::indexSet ( ) const

inline

Checks if interface index has been set.

Returns: true if interface index set, false otherwise.

Definition at line 672 of file pkt.h.

References ifindex_, and isc::dhcp::UNSET_IFINDEX.

◆ isCopyRetrievedOptions()

bool isc::dhcp::Pkt::isCopyRetrievedOptions ( ) const

inline

Returns whether the copying of retrieved options is enabled.

Also see setCopyRetrievedOptions.

Returns: true if retrieved options are copied.

Definition at line 496 of file pkt.h.

References copy_retrieved_options_.

◆ len()

virtual size_t isc::dhcp::Pkt::len ( )

pure virtual

Returns packet size in binary format.

Returns size of the packet in on-wire format or size needed to store it in on-wire format.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt4 and Pkt6 class have respective implementations of this method.

Returns: packet size in bytes

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

Referenced by Pkt().

◆ pack()

virtual void isc::dhcp::Pkt::pack ( )

pure virtual

Prepares on-wire format of DHCP (either v4 or v6) packet.

Prepares on-wire format of message and all its options. A caller must ensure that options are stored in options_ field prior to calling this method.

Output buffer will be stored in buffer_out_. The buffer_out_ should be cleared before writing to the buffer in the derived classes.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt4 and Pkt6 class have respective implementations of this method.

Exceptions

InvalidOperation if packing fails

Implemented in isc::dhcp::Pkt4, isc::dhcp::Pkt4o6, and isc::dhcp::Pkt6.

◆ repack()

void isc::dhcp::Pkt::repack ( )

Copies content of input buffer to output buffer.

This is mostly a diagnostic function. It is being used for sending received packet. Received packet is stored in data_, but transmitted data is stored in buffer_out_. If we want to send packet that we just received, a copy between those two buffers is necessary.

Definition at line 151 of file pkt.cc.

References buffer_out_, data_, and isc::util::OutputBuffer::writeData().

Here is the call graph for this function:

◆ resetIndex()

void isc::dhcp::Pkt::resetIndex ( )

inline

Resets interface index to negative value.

Definition at line 658 of file pkt.h.

References ifindex_, and isc::dhcp::UNSET_IFINDEX.

◆ setCopyRetrievedOptions()

virtual void isc::dhcp::Pkt::setCopyRetrievedOptions ( const bool copy )

inlinevirtual

Controls whether the option retrieved by the Pkt::getOption should be copied before being returned.

Setting this value to true enables the mechanism of copying options retrieved from the packet to prevent accidental modifications of options that shouldn't be modified. The typical use case for this mechanism is to prevent hook library from modifying instance of an option within the packet that would also affect the value for this option within the Kea configuration structures.

Kea doesn't copy option instances which it stores in the packet. It merely copy pointers into the packets. Thus, any modification to an option would change the value of this option in the Kea configuration. To prevent this, option copying should be enabled prior to passing the pointer to a packet to a hook library.

Not only does this method cause the server to copy an option, but the copied option also replaces the original option within the packet. The option can be then freely modified and the modifications will only affect the instance of this option within the packet but not within the server configuration.

Parameters

copy	Indicates if the options should be copied when retrieved (if true), or not copied (if false).

Reimplemented in isc::dhcp::Pkt4o6.

Definition at line 487 of file pkt.h.

References isc::data::copy(), and copy_retrieved_options_.

Referenced by isc::dhcp::Pkt4o6::setCopyRetrievedOptions().

Here is the call graph for this function:

◆ setIface()

void isc::dhcp::Pkt::setIface ( const std::string & iface )

inline

Sets interface name.

Sets interface name over which packet was received or is going to be transmitted.

Parameters

iface The interface name

Definition at line 692 of file pkt.h.

References iface_.

Referenced by isc::dhcp::Pkt4o6::Pkt4o6().

◆ setIndex()

void isc::dhcp::Pkt::setIndex ( const unsigned int ifindex )

inline

Sets interface index.

Parameters

ifindex specifies interface index.

Definition at line 653 of file pkt.h.

References ifindex_.

Referenced by isc::dhcp::Pkt4o6::Pkt4o6().

◆ setLocalAddr()

void isc::dhcp::Pkt::setLocalAddr ( const isc::asiolink::IOAddress & local )

inline

Sets local IP address.

Parameters

local specifies local address

Definition at line 602 of file pkt.h.

References local_addr_.

◆ setLocalPort()

void isc::dhcp::Pkt::setLocalPort ( uint16_t local )

inline

Sets local UDP (and soon TCP) port.

This sets a local port, i.e. destination port for recently received packet or a source port for to be transmitted packet.

Parameters

local specifies local port

Definition at line 619 of file pkt.h.

References local_port_.

◆ setPktEvent()

void isc::dhcp::Pkt::setPktEvent	(	const std::string &	label,
		const boost::posix_time::ptime &	timestamp = PktEvent::now() )

Updates (or adds) an event in the event stack.

Updates the timestamp of the event described by label if it exists in the stack, otherwise it adds the event to the end of the stack. This is intended to be used for testing.

Parameters

label	string identifying the event
timestamp	time at which the event occurred. It is expected to be in UTC/microseconds.

Definition at line 326 of file pkt.cc.

◆ setRemoteAddr()

void isc::dhcp::Pkt::setRemoteAddr ( const isc::asiolink::IOAddress & remote )

inline

Sets remote IP address.

Parameters

remote specifies remote address

Definition at line 588 of file pkt.h.

References remote_addr_.

Referenced by isc::dhcp::Pkt4o6::Pkt4o6().

◆ setRemoteHWAddr() [1/2]

void isc::dhcp::Pkt::setRemoteHWAddr ( const HWAddrPtr & hw_addr )

Sets remote hardware address.

Sets hardware address (MAC) from an existing HWAddr structure. The remote address is a destination address for outgoing packet and source address for incoming packet. When this is an outgoing packet, this address will be used to construct the link layer header.

Parameters

hw_addr structure representing HW address.

Exceptions

BadValue if addr is null

Definition at line 164 of file pkt.cc.

References isc_throw, and remote_hwaddr_.

◆ setRemoteHWAddr() [2/2]

void isc::dhcp::Pkt::setRemoteHWAddr	(	const uint8_t	htype,
		const uint8_t	hlen,
		const std::vector< uint8_t > &	hw_addr )

Sets remote hardware address.

Sets the destination hardware (MAC) address for the outgoing packet or source HW address for the incoming packet. When this is an outgoing packet this address will be used to construct the link layer header.

Note: mac_addr must be a buffer of at least hlen bytes.

In a typical case, hlen field would be redundant, as it could be extracted from mac_addr.size(). However, the difference is when running on exotic hardware, like Infiniband, that had MAC addresses 20 bytes long. In that case, hlen is set to zero in DHCPv4.

Parameters

htype	hardware type (will be sent in htype field)
hlen	hardware length (will be sent in hlen field)
hw_addr	pointer to hardware address

Definition at line 158 of file pkt.cc.

References remote_hwaddr_.

◆ setRemotePort()

void isc::dhcp::Pkt::setRemotePort ( uint16_t remote )

inline

Sets remote UDP (and soon TCP) port.

This sets a remote port, i.e. source port for recently received packet or a destination port for to be transmitted packet.

Parameters

remote specifies remote port

Definition at line 639 of file pkt.h.

References remote_port_.

◆ setTimestamp()

void isc::dhcp::Pkt::setTimestamp ( boost::posix_time::ptime & timestamp )

inline

Set socket receive timestamp.

Sets the socket receive timestamp to an arbitrary value.

Definition at line 521 of file pkt.h.

References timestamp_.

◆ setTransid()

void isc::dhcp::Pkt::setTransid ( uint32_t transid )

inline

Sets transaction-id value.

Parameters

transid transaction-id to be set.

Definition at line 334 of file pkt.h.

References transid_.

Referenced by isc::perfdhcp::PerfPkt4::PerfPkt4(), isc::perfdhcp::PerfPkt6::PerfPkt6(), isc::perfdhcp::PerfPkt4::rawUnpack(), and isc::perfdhcp::PerfPkt6::rawUnpack().

◆ setType()

virtual void isc::dhcp::Pkt::setType ( uint8_t type )

pure virtual

Sets message type (e.g.

1 = SOLICIT).

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt4 and Pkt6 class have respective implementations of this method.

Parameters

type	message type to be set

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

◆ toText()

virtual std::string isc::dhcp::Pkt::toText ( ) const

pure virtual

Returns text representation of the packet.

This function is useful mainly for debugging.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt4 and Pkt6 class have respective implementations of this method.

Returns: string with text representation

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

◆ unpack()

virtual void isc::dhcp::Pkt::unpack ( )

pure virtual

Parses on-wire form of DHCP (either v4 or v6) packet.

Parses received packet, stored in on-wire format in data_.

Will create a collection of option objects that will be stored in options_ container.

Note: This is a pure virtual method and must be implemented in the derived classes. The Pkt4 and Pkt6 class have respective implementations of this method.

Method will throw exception if packet parsing fails.

Exceptions

tbd

Implemented in isc::dhcp::Pkt4, and isc::dhcp::Pkt6.

◆ updateTimestamp()

void isc::dhcp::Pkt::updateTimestamp ( )

Update packet timestamp.

Updates packet timestamp. This method is invoked by interface manager just before sending or just after receiving it.

Exceptions

isc::Unexpected if timestamp update failed

Definition at line 147 of file pkt.cc.

References timestamp_.

Member Data Documentation

◆ buffer_out_

isc::util::OutputBuffer isc::dhcp::Pkt::buffer_out_

protected

Output buffer (used during message transmission)

Warning: This protected member is accessed by derived classes directly. One of such derived classes is perfdhcp::PerfPkt6. The impact on derived classes' behavior must be taken into consideration before making changes to this member such as access scope restriction or data format change etc.

Definition at line 946 of file pkt.h.

Referenced by getBuffer(), isc::dhcp::Pkt4::pack(), isc::dhcp::Pkt6::packUDP(), isc::perfdhcp::PerfPkt4::rawPack(), isc::perfdhcp::PerfPkt6::rawPack(), and repack().

◆ classes_

ClientClasses isc::dhcp::Pkt::classes_

Classes this packet belongs to.

This field is public, so the code outside of Pkt4 or Pkt6 class can iterate over existing classes. Having it public also solves the problem of returned reference lifetime. It is preferred to use inClass and addClass to operate on this field.

Definition at line 770 of file pkt.h.

Referenced by addClass(), addSubClass(), getClasses(), and inClass().

◆ copy_retrieved_options_

bool isc::dhcp::Pkt::copy_retrieved_options_

protected

Indicates if a copy of the retrieved option should be returned when Pkt::getOption is called.

See also: the documentation for Pkt::setCopyRetrievedOptions.

Definition at line 952 of file pkt.h.

Referenced by isc::dhcp::Pkt6::getAllRelayOptions(), getOption(), getOptions(), isc::dhcp::Pkt6::getRelayOption(), isc::dhcp::Pkt6::getRelayOptions(), isCopyRetrievedOptions(), and setCopyRetrievedOptions().

◆ data_

OptionBuffer isc::dhcp::Pkt::data_

Unparsed data (in received packets).

Warning: This public member is accessed by derived classes directly. One of such derived classes is perfdhcp::PerfPkt6. The impact on derived classes' behavior must be taken into consideration before making changes to this member such as access scope restriction or data format change etc.

Definition at line 404 of file pkt.h.

Referenced by Pkt(), isc::perfdhcp::PerfPkt4::rawPack(), isc::perfdhcp::PerfPkt6::rawPack(), isc::perfdhcp::PerfPkt4::rawUnpack(), isc::perfdhcp::PerfPkt6::rawUnpack(), repack(), isc::dhcp::Pkt4::unpack(), isc::dhcp::Pkt6::unpackMsg(), isc::dhcp::Pkt6::unpackRelayMsg(), isc::dhcp::Pkt6::unpackUDP(), isc::perfdhcp::PerfPkt4::writeAt(), isc::perfdhcp::PerfPkt6::writeAt(), isc::perfdhcp::PerfPkt4::writeValueAt(), and isc::perfdhcp::PerfPkt6::writeValueAt().

◆ iface_

std::string isc::dhcp::Pkt::iface_

protected

Name of the network interface the packet was received/to be sent over.

Definition at line 911 of file pkt.h.

Referenced by getIface(), getMACFromIPv6(), isc::dhcp::Pkt6::getMACFromRemoteIdRelayOption(), and setIface().

◆ ifindex_

unsigned int isc::dhcp::Pkt::ifindex_

protected

Interface index.

Each network interface has assigned an unique ifindex. It is a functional equivalent of a name, but sometimes more useful, e.g. when using odd systems that allow spaces in interface names.

Definition at line 918 of file pkt.h.

Referenced by getIndex(), indexSet(), resetIndex(), and setIndex().

◆ local_addr_

isc::asiolink::IOAddress isc::dhcp::Pkt::local_addr_

protected

Local IP (v4 or v6) address.

Specifies local IPv4 or IPv6 address. It is a destination address for received packet, and a source address if it packet is being transmitted.

Definition at line 924 of file pkt.h.

Referenced by getLocalAddr(), setLocalAddr(), isc::dhcp::Pkt4::toText(), and isc::dhcp::Pkt6::toText().

◆ local_port_

uint16_t isc::dhcp::Pkt::local_port_

protected

local TDP or UDP port

Definition at line 933 of file pkt.h.

Referenced by getLocalPort(), setLocalPort(), isc::dhcp::Pkt4::toText(), and isc::dhcp::Pkt6::toText().

◆ options_

isc::dhcp::OptionCollection isc::dhcp::Pkt::options_

Collection of options present in this message.

Warning: This public member is accessed by derived classes directly. One of such derived classes is perfdhcp::PerfPkt6. The impact on derived classes' behavior must be taken into consideration before making changes to this member such as access scope restriction or data format change etc.

Definition at line 796 of file pkt.h.

Referenced by addOption(), cloneOptions(), delOption(), isc::dhcp::Pkt6::directLen(), getNonCopiedOption(), getNonCopiedOptions(), isc::dhcp::Pkt6::getNonCopiedRelayOption(), getOption(), getOptions(), isc::dhcp::Pkt6::getRelayOption(), isc::dhcp::Pkt4::len(), isc::dhcp::Pkt4::pack(), isc::dhcp::Pkt6::packUDP(), isc::perfdhcp::PerfPkt4::rawPack(), isc::perfdhcp::PerfPkt6::rawPack(), isc::perfdhcp::PerfPkt4::rawUnpack(), isc::perfdhcp::PerfPkt6::rawUnpack(), isc::dhcp::Pkt4::toText(), isc::dhcp::Pkt6::RelayInfo::toText(), isc::dhcp::Pkt6::toText(), isc::dhcp::Pkt4::unpack(), and isc::dhcp::Pkt6::unpackMsg().

◆ remote_addr_

isc::asiolink::IOAddress isc::dhcp::Pkt::remote_addr_

protected

Remote IP address.

Specifies local IPv4 or IPv6 address. It is source address for received packet and a destination address for packet being transmitted.

Definition at line 930 of file pkt.h.

Referenced by isc::dhcp::Pkt6::getMACFromSrcLinkLocalAddr(), getRemoteAddr(), setRemoteAddr(), isc::dhcp::Pkt4::toText(), and isc::dhcp::Pkt6::toText().

◆ remote_hwaddr_

HWAddrPtr isc::dhcp::Pkt::remote_hwaddr_

protected

Definition at line 958 of file pkt.h.

Referenced by getRemoteHWAddr(), setRemoteHWAddr(), and setRemoteHWAddr().

◆ remote_port_

uint16_t isc::dhcp::Pkt::remote_port_

protected

remote TCP or UDP port

Definition at line 936 of file pkt.h.

Referenced by getRemotePort(), setRemotePort(), isc::dhcp::Pkt4::toText(), and isc::dhcp::Pkt6::toText().

◆ required_classes_

ClientClasses isc::dhcp::Pkt::required_classes_

Classes which are required to be evaluated.

The comment on classes_ applies here.

Before output option processing these classes will be evaluated and if evaluation status is true added to the previous collection.

Definition at line 778 of file pkt.h.

Referenced by addClass(), and getClasses().

◆ subclasses_

SubClassRelationContainer isc::dhcp::Pkt::subclasses_

SubClasses this packet belongs to.

This field is public, so the code outside of Pkt4 or Pkt6 class can iterate over existing classes. Having it public also solves the problem of returned reference lifetime. It is preferred to use inClass and addSubClass to operate on this field.

Definition at line 786 of file pkt.h.

Referenced by addClass(), addSubClass(), and getSubClassesRelations().

◆ timestamp_

boost::posix_time::ptime isc::dhcp::Pkt::timestamp_

protected

packet timestamp

Definition at line 955 of file pkt.h.

Referenced by getTimestamp(), setTimestamp(), and updateTimestamp().

◆ transid_

uint32_t isc::dhcp::Pkt::transid_

protected

Transaction-id (32 bits for v4, 24 bits for v6)

Definition at line 908 of file pkt.h.

Referenced by isc::dhcp::Pkt4::getLabel(), getTransid(), isc::dhcp::Pkt4::pack(), isc::dhcp::Pkt6::packUDP(), setTransid(), isc::dhcp::Pkt4::toText(), isc::dhcp::Pkt6::toText(), isc::dhcp::Pkt4::unpack(), and isc::dhcp::Pkt6::unpackMsg().

The documentation for this class was generated from the following files:

pkt.h
pkt.cc

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Pkt() [1/2]

◆ Pkt() [2/2]

◆ ~Pkt()

Member Function Documentation

◆ addClass()

◆ addOption()

◆ addPktEvent() [1/2]

◆ addPktEvent() [2/2]

◆ addSubClass()

◆ clearPktEvents()

◆ cloneOptions()

◆ delOption()

◆ dumpPktEvents()

◆ getBuffer()

◆ getClasses()

◆ getIface()

◆ getIndex()

◆ getLabel()

◆ getLocalAddr()

◆ getLocalPort()

◆ getMAC()

◆ getMACFromDocsisCMTS()

◆ getMACFromDocsisModem()

◆ getMACFromDUID()

◆ getMACFromIPv6()

◆ getMACFromIPv6RelayOpt()

◆ getMACFromRemoteIdRelayOption()

◆ getMACFromSrcLinkLocalAddr()

◆ getName()

◆ getNonCopiedOption()

◆ getNonCopiedOptions()

◆ getOption()

◆ getOptions()

◆ getPktEvents()

◆ getPktEventTime()

◆ getRemoteAddr()

◆ getRemoteHWAddr()

◆ getRemotePort()

◆ getSubClassesRelations()

◆ getTimestamp()

◆ getTransid()

◆ getType()

◆ inClass()

◆ indexSet()

◆ isCopyRetrievedOptions()

◆ len()

◆ pack()

◆ repack()

◆ resetIndex()

◆ setCopyRetrievedOptions()

◆ setIface()

◆ setIndex()

◆ setLocalAddr()

◆ setLocalPort()

◆ setPktEvent()

◆ setRemoteAddr()

◆ setRemoteHWAddr() [1/2]

◆ setRemoteHWAddr() [2/2]

◆ setRemotePort()

◆ setTimestamp()

◆ setTransid()

◆ setType()

◆ toText()

◆ unpack()

◆ updateTimestamp()

Member Data Documentation

◆ buffer_out_

◆ classes_

◆ copy_retrieved_options_

◆ data_

◆ iface_

◆ ifindex_

◆ local_addr_

◆ local_port_