DTC: DHCP Transaction Cache
===========================

The system provides a Python object :data:`alc.dtc`, which is an instance of :data:`alc.Dtc`, that allows data to be cached temporarily between DHCP packets.

   .. note::
      Only the pre-provided :data:`alc.dtc` object should be used in script, the class :data:`alc.Dtc` should not be used directly.

A DHCP transaction cache (DTC) is a short-lived cache during a DHCPv4/v6 transaction. The cache can be used to store user-chosen information or return ESM attributes. The DTC’s lifetime is only during a single DHCP transaction (for example, only between discovery and offer, or request and reply). This includes both alc.dtc.store() data and alc.dtc.setESM() data. DTC is also a transaction-specific cache, which means the cached information can only be accessed by the Python script running in the same DHCP transaction.

.. _alc_dot_dtc:

The :data:`alc.Dtc` class
--------------------------

Instance Attributes
^^^^^^^^^^^^^^^^^^^

.. attribute:: derivedId

   The `derivedId` attribute is an attribute which can be set by a Python script and be used as a LUDB match criterion. The current value can be read from this attribute. A new value for the derivedId can be set by assigning a new value to this attribute.

   The type of this attribute is `str`.

   If the derivedId is not supported, a RuntimeException is raised when retrieving or setting this attribute.

   If no derivedId has been set, `None` is returned.
   This behavior has :ref:`changed<breaking-dtc-no-derived-id>` with respect to the Python 2 implementation.

Methods
^^^^^^^

.. method:: store(key, value, /)

    Stores a value associated with a key.

    :param key str: key to associate the value with
    :param value bytes: value to cache
    :raises RuntimeError: if the value cannot be stored.


.. method:: retrieve(key, /)

    Retrieves a previously stored value.

    :param key str: key the value was associated with
    :raises KeyError: if no value is associated with the specified key


.. method:: setESM(key, value, /)

    Sets an attribute on the current subscriber to the specified value.

    :param key int: Integer representing which attribute to set.
                    See :ref:`dtc_constants` for an enumeration of all supported attributes.
    :param value: value to set the attribute to
    :raises: KeyError if the key is not valid
    :raises: ValueError if the type of the value or the actual value is not valid for the specified key.


.. method:: setDhcpv6LinkAddr(value, /)

    Sets the DHCPv6 link-address.

    :param value bytes: the bytes-representation of an IPv6-address to set as link-address


.. method:: setDhcpv6ServerAddr(value, /)

    Sets the DHCPv6 server-address.

    :param value bytes: the bytes-representation of an IPv6-address to set as server-address

.. _dtc_constants:

Constants
^^^^^^^^^

The :data:`alc.dtc` object provides a list of constants which can be used as a key parameter to choose which attribute to set.
The following table lists all attributes and the supported object-types for the corresponding value.

.. list-table::
   :header-rows: 1
   
   * - Attribute
     - Types
   * - subIdent
     - str 
   * - subProfileString
     - str 
   * - slaProfileString
     - str 
   * - ancpString
     - str 
   * - appProfileString
     - str 
   * - intDestId
     - str 
   * - catMapString
     - str 
   * - msapGroupInterface
     - str 
   * - msapPolicy
     - str 
   * - msapServiceId
     - str | int
   * - retailServiceId
     - str  | int
   * - ipAddress
     - str 
   * - ipv6Address
     - str 
   * - ipv6DelegatedPrefix
     - str 
   * - ipv6DelegatedPrefixLength
     - int
   * - ipv6SlaacPrefix
     - str 
   * - ipv6WanPool
     - str 
   * - ipv6PrefixPool
     - str 
   * - accountingPolicy
     - str 
   * - dhcpv4ServerAddr
     - str 
   * - dhcpv4GIAddr
     - str 
   * - dhcpv4SrcAddr
     - str 
   * - dhcpv4Pool
     - str 
   * - dhcpv6LinkAddr
     - str 
   * - dhcpv6ServerAddr
     - str 
   * - dhcpv6SrcAddr
     - str 
   * - defGw
     - str 
   * - subnetMask
     - str 
   * - ipv4LeaseTime
     - int 
   * - ipv4PrimDns
     - str 
   * - ipv4SecDns
     - str 
   * - primNbns
     - str 
   * - secNbns
     - str 
   * - ipv6PrimDns
     - str 
   * - ipv6SecDns
     - str 
   * - dhcpv6PreferredLifetime
     - int 
   * - dhcpv6RebindTimer
     - int 
   * - dhcpv6RenewTimer
     - int 
   * - dhcpv6ValidLifetime
     - int 
   * - spiSharingGroupId
     - int


.. _breaking-dtc:

Breaking changes
----------------

.. _breaking-dtc-no-derived-id:

Derived Id
^^^^^^^^^^
.. warning:: With Python 2 API, reading a derived-id which is not yet set raises a RuntimeError.  With Python 3, the value `None` is returned.