GTP
===

The system provides the Python object :data:`alc.gtp2c`, an instance of :data:`alc.gtp2c`, to inspect and modify GTPv2 control packets.

   .. note::
     For GTP-2c messages, only the pre-provided :data:`alc.gtp2c` object should be used in scripts; the :data:`alc.gtp2c` class should not be used directly.

.. _alc_dot_gtp2c:

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

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

The GTP-2c header fields are exposed as instance attributes on the object.

.. list-table:: Attributes defined on alc.gtp2c
   :header-rows: 1
   
   * - Attribute
     - Field
     - Access
     - Type
   * - version
     - GTP version field
     - ro
     - int
   * - pbit
     - Piggyback flag
     - ro
     - int
   * - tbit
     - Flag marking if there is a TEID present.
     - ro
     - int
   * - type
     - Type of the GTP message
     - ro
     - int
   * - len
     - Length of the GTP message
     - ro
     - int
   * - teid
     - Tunnel Endpoint Identifier. `None` if not present
     - ro
     - int
   * - seq
     - Sequence number
     - ro
     - int

Methods
^^^^^^^

.. method:: drop()

   Drops the packet.


.. method:: getIEList()

   Returns a list of IE types that are present in the packet.

   - If there are multiple instances of the same IE, the IE type appears multiple times in the list.
   

.. method:: get(type, instance, /)

   Returns all values of the IEs with the specified type.  The values are returned as the exact bytestrings as they appear in the packet.
   
   - If the specified option does not exist, the result is an empty tuple: ()
   - If a specific instance has zero length or no values, the corresponding bytestring is an empty bytestring: b""

   :param int type: IE type
   :param int instance: IE instance
   :rtype: tuple of bytestrings

.. method:: set(type, instance, value, /)

   Deletes existing IEs with the specified type and instance and inserts new IEs with the specified type, instance, and value. Multiple values can be specified in a tuple, in which case an option is added for each item in the tuple.

   :param int type: IE type
   :param int instance: IE instance
   :param bytes|tuple(bytes) value: value of the option; the length is determined automatically from this value


.. method:: clear(type, instance, /)

   Removes all IEs with the specified type.

   :param int type: IE type
   :param int instance: IE instance

.. method:: decode_grouped_ie(value)

   Decodes the byte representation of a grouped IE to a tuple of IEs.

   Defined as a static method.

   :param bytes value: grouped IE value
   :return: returns a tuple where each element represents an IE. Each IE is represented as a tuple (type, instance, value) with types (int, int, bytes).

.. method:: encode_grouped_ie(value)

   Encodes a tuple of IEs into the byte representation of a grouped IE.

   Defined as a static method.

   :param tuple value: tuple of IEs where each IE is represented as a (type, instance, value) tuple.
   :return: byte representation of the grouped IE


.. method:: get_pco()

   Returns the PCO IE (78) as a :class:`alc.Pco` object.

   The returned object can be modified in-place and is reflected in the resulting GTP packet.

   :return: A :class:`alc.Pco` object

.. method:: set_pco(pco)

   Accepts a :class:`alc.Pco` object, encodes it, and uses this as the value for the PCO IE.

   :param `alc.pco` pco: :class:`alc.Pco` object



The :class:`alc.Pco` class
--------------------------

.. class:: alc.Pco(bytes, /)

    Creates a new object representing a PCO IE.

    :param bytes bytes: the bytes representation of the PCO IE.
   
Instance Attributes
^^^^^^^^^^^^^^^^^^^

.. list-table:: Attributes defined on alc.Pco objects
   :header-rows: 1
   
   * - Attribute
     - Field
     - Access
     - Type
   * - proto
     - Protocol field
     - ro
     - int
   * - length
     - Length of the embedded protocol
     - ro
     - int

Methods
^^^^^^^

.. method:: get_container(id, /)

   Retrieves the content of all containers with the specified ID.

   :param int id: ID of the container
   :rtype: list(bytes)

.. method:: set_container(id, container, /)

   Deletes existing containers of the specified ID and inserts new containers. Multiple containers can be specified in a tuple, in which case a container is added for each entry in the tuple.

   Containers of type PAP, CHAP, IPCP, or LCP cannot be modified with this method. See :meth:`set_pap` and :meth:`set_chap`.

   :param int id: ID of the container
   :param container: content of the container
   :type container: bytes or tuple(bytes)

.. method:: clear_container(id, /)

   Removes all containers with the specified ID.

   :param int id: ID of the container

.. method:: get_pap()

   Returns the PAP container as a :class:`alc.Pap` object.

.. method:: set_pap(pap, /)

   Replaces the existing PAP container with a new one. Multiple PAP objects can be specified in a tuple.

   :param pap: PAP object
   :type pap: :class:`alc.Pap` or tuple(:class:`alc.Pap`)

.. method:: clear_pap()

   Removes all PAP containers.

.. method:: get_chap()

   Returns the CHAP container as a :class:`alc.Chap` object.

.. method:: set_chap(chap, /)

   Replaces the existing CHAP container with a new one. Multiple CHAP objects can be specified in a tuple.

   :param chap: CHAP object
   :type chap: :class:`alc.Chap` or tuple(:class:`alc.Chap`)

.. method:: clear_chap()

   Removes all CHAP containers.