Kea 2.5.8
isc::dhcp::Pkt Class Referenceabstract

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::OutputBuffergetBuffer ()
 Returns reference to output buffer.
 
const ClientClassesgetClasses (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::IOAddressgetLocalAddr () 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::IOAddressgetRemoteAddr () 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 SubClassRelationContainergetSubClassesRelations () 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
transidtransaction-id
local_addrlocal IPv4 or IPv6 address
remote_addrremote IPv4 or IPv6 address
local_portlocal UDP (one day also TCP) port
remote_portremote 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
bufpointer to a buffer that contains on-wire data
lenlength of the pointer specified in buf
local_addrlocal IPv4 or IPv6 address
remote_addrremote IPv4 or IPv6 address
local_portlocal UDP (one day also TCP) port
remote_portremote 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_classname of the class to be added
requiredthe class is marked for required evaluation

Definition at line 126 of file pkt.cc.

References classes_, isc::dhcp::ClientClasses::contains(), 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
optoption 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
labelstring identifying the event
timestamptime 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
labelstring identifying the event
timestamptime 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_defname of the class definition to be added
subclassname 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
typeType 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
verbosewhen 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
requiredreturn 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_.

Referenced by isc::dhcp::TokenPkt::evaluate().

◆ 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_.

Referenced by isc::dhcp::TokenPkt::evaluate().

◆ 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_srca 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
addrIPv6 address to be converted
Returns
hardware address (or NULL)

Definition at line 277 of file pkt.cc.

References isc::dhcp::IfaceMgr::getIface(), 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
typeOption 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_typeOption 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
typeoption 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_.

Referenced by isc::dhcp::TokenVendor::evaluate(), isc::dhcp::TokenVendorClass::evaluate(), isc::dhcp::TokenOption::getOption(), isc::dhcp::TokenRelay4Option::getOption(), and isc::dhcp::TokenVendor::getOption().

◆ 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
typeoption 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
labelstring 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_.

Referenced by isc::dhcp::TokenPkt::evaluate().

◆ 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

◆ 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_classname of the class
Returns
true if belongs

Definition at line 121 of file pkt.cc.

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

Referenced by isc::dhcp::TokenMember::evaluate().

+ 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
InvalidOperationif 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
copyIndicates 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
ifaceThe 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
ifindexspecifies 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
localspecifies 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
localspecifies 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
labelstring identifying the event
timestamptime 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
remotespecifies 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_addrstructure representing HW address.
Exceptions
BadValueif 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
htypehardware type (will be sent in htype field)
hlenhardware length (will be sent in hlen field)
hw_addrpointer 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
remotespecifies 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
transidtransaction-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
typemessage 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::Unexpectedif 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(), 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

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