:right-sidebar: True

MessageBody
===================================================================

.. currentmodule:: gi.repository.Soup





.. class:: MessageBody(**kwargs)
   :no-contents-entry:






:obj:`~gi.repository.Soup.MessageBody` represents the request or response body of a
:obj:`~gi.repository.Soup.Message`\.

Note that while ``length`` always reflects the full length of the
message body, ``data`` is normally :const:`None`, and will only be filled in
after :obj:`~gi.repository.MessageBody.flatten` is called. For client-side
messages, this automatically happens for the response body after it
has been fully read. Likewise, for server-side
messages, the request body is automatically filled in after being
read.

As an added bonus, when ``data`` is filled in, it is always terminated
with a ``\0`` byte (which is not reflected in ``length``\).


Constructors
------------

.. rst-class:: interim-class

.. class:: MessageBody
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Soup.MessageBody

      Creates a new :obj:`~gi.repository.Soup.MessageBody`\.

      :obj:`~gi.repository.Soup.Message` uses this internally; you
      will not normally need to call it yourself.













Methods
-------

.. rst-class:: interim-class

.. class:: MessageBody
   :no-index:


   .. method:: append(data: list[int]) -> None

      Appends ``length`` bytes from ``data`` to ``body`` according to ``use``\.






      :param data: data to append




   .. method:: append_bytes(buffer: ~gi.repository.GLib.Bytes) -> None

      Appends the data from ``buffer`` to ``body``\.






      :param buffer: a :obj:`~gi.repository.GLib.Bytes`




   .. method:: complete() -> None

      Tags ``body`` as being complete.

      Call this when using chunked encoding after you have appended the last chunk.









   .. method:: flatten() -> ~gi.repository.GLib.Bytes

      Fills in ``body``\'s data field with a buffer containing all of the
      data in ``body``\.

      Adds an additional ``\0`` byte not counted by ``body``\'s
      length field.









   .. method:: get_accumulate() -> bool

      Gets the accumulate flag on ``body``\.

      See [method``MessageBody``\.set_accumulate. for details.









   .. method:: get_chunk(offset: int) -> ~gi.repository.GLib.Bytes | None

      Gets a :obj:`~gi.repository.GLib.Bytes` containing data from ``body`` starting at ``offset``\.

      The size of the returned chunk is unspecified. You can iterate
      through the entire body by first calling
      :obj:`~gi.repository.MessageBody.get_chunk` with an offset of 0, and then on each
      successive call, increment the offset by the length of the
      previously-returned chunk.

      If ``offset`` is greater than or equal to the total length of ``body``\,
      then the return value depends on whether or not
      :obj:`~gi.repository.MessageBody.complete` has been called or not; if it has,
      then :obj:`~gi.repository.MessageBody.get_chunk` will return a 0-length chunk
      (indicating the end of ``body``\). If it has not, then
      :obj:`~gi.repository.MessageBody.get_chunk` will return :const:`None` (indicating that
      ``body`` may still potentially have more data, but that data is not
      currently available).






      :param offset: an offset




   .. method:: got_chunk(chunk: ~gi.repository.GLib.Bytes) -> None

      Handles the :obj:`~gi.repository.Soup.MessageBody` part of receiving a chunk of data from
      the network.

      Normally this means appending ``chunk`` to ``body``\, exactly as with
      :obj:`~gi.repository.MessageBody.append_bytes`\, but if you have set ``body``\'s accumulate
      flag to :const:`False`, then that will not happen.

      This is a low-level method which you should not normally need to
      use.






      :param chunk: a :obj:`~gi.repository.GLib.Bytes` received from the network




   .. method:: set_accumulate(accumulate: bool) -> None

      Sets or clears the accumulate flag on ``body``\.

      (The default value is :const:`True`.) If set to :const:`False`, ``body``\'s data field will not
      be filled in after the body is fully sent/received, and the chunks that make
      up ``body`` may be discarded when they are no longer needed.

      If you set the flag to :const:`False` on the :obj:`~gi.repository.Soup.Message` request_body of a
      client-side message, it will block the accumulation of chunks into
      ``body``\'s data field, but it will not normally cause the chunks to
      be discarded after being written like in the server-side
      :obj:`~gi.repository.Soup.Message` response_body case, because the request body needs to
      be kept around in case the request needs to be sent a second time
      due to redirection or authentication.






      :param accumulate: whether or not to accumulate body chunks in ``body``




   .. method:: truncate() -> None

      Deletes all of the data in ``body``\.









   .. method:: wrote_chunk(chunk: ~gi.repository.GLib.Bytes) -> None

      Handles the :obj:`~gi.repository.Soup.MessageBody` part of writing a chunk of data to the
      network.

      Normally this is a no-op, but if you have set ``body``\'s accumulate flag to
      :const:`False`, then this will cause ``chunk`` to be discarded to free up memory.

      This is a low-level method which you should not need to use, and
      there are further restrictions on its proper use which are not
      documented here.






      :param chunk: a :obj:`~gi.repository.GLib.Bytes` returned from :obj:`~gi.repository.MessageBody.get_chunk`














Fields
------

.. rst-class:: interim-class

.. class:: MessageBody
   :no-index:
   

   .. attribute:: data

      The data






   .. attribute:: length

      Length of ``data``