GTP
===

The system provides two Python objects :data:`alc.gtp1c`, an instance of :data:`alc.Gtp1c`,  and :data:`alc.gtp2c`, and instance of class :data:`alc.Gtp1c`, to inspect and modify the GTPv1 and GTPv2 control packet.

   .. note::
     For GTP-1c/GTP-2c message, only the pre-provided :data:`alc.gtp1c`/:data:`alc.gtp2c` object should be used in script, the class :data:`alc.Gtp1c`/:data:`alc.Gtp2c` should not be used directly.

.. _alc_dot_gtp1c:

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

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

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

.. list-table:: Attributes defined on alc.gtp1c
   :header-rows: 1
   
   * - Attribute
     - Field
     - Access
     - Type
   * - version
     - GTP version field
     - ro
     - int
   * - ptbit
     - Protocol Type bit
     - ro
     - int
   * - ebit
     - Flag marking if there is an extension header.
     - ro
     - int
   * - sbit
     - Flag marking if there is a sequence-number field.
     - ro
     - int
   * - pnbit
     - Flag marking if there is an N-PDU field.
     - ro
     - int
   * - type
     - Type of the GTP message
     - ro
     - int
   * - len
     - Length of the GTP message
     - ro
     - int
   * - teid
     - Tunnel Endpoint Identifier
     - ro
     - int
   * - seq
     - Sequence number. `None` if not present.
     - ro
     - int
   * - npdu_number
     - N-PDU number. `None` if not present.
     - ro
     - int
   * - next_ext_type
     - Next extension type. `None` if not present
     - ro
     - int
   * - ext_list
     - List of extension-headers, repesented as a tuple (type, value)
     - ro
     - list of (int, bytes) tuples

Methods
^^^^^^^

.. method:: drop()

   Drops the packet.


.. method:: getIEList()

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

   - The order of the elements is the same as they appear in the packet.
   - If there are multiple instances of the same IE, the IE-type appears multiple times in the tuple.
   

.. method:: get(type, /)

   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 in the result tuple is an empty bytestring: b""

   :param int type: IE-type to fetch
   :rtype: tuple of bytestrings

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

   Deletes existing IEs of the specified type and inserts new IEs with the specified type 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 to set
   :param bytes|tuple(bytes) value: value of the option; length is computed from this value


.. method:: clear(type, /)

   Removes all IEs with the specified type.

   :param int type: IE-type to clear

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

   - The order of the elements is the same as they appear in the packet.
   - If there are multiple instances of the same IE, the IE-type appears multiple times in the tuple.
   

.. 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, length is computed 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.


.. _breaking-gtp:

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


.. _breaking-gtp-renames:

Renamed methods
^^^^^^^^^^^^^^^

.. warning:: The following methods of :class:`alc.Gtp2c` class have been renamed in Python 3 API:

   * Python 2 str_to_groupedIE is now Python 3 :meth:`alc.Gtp2c.decode_grouped_ie`
   * Python 2 groupedIE_to_str is now Python 3 :meth:`alc.Gtp2c.encode_grouped_ie`