godot-docs/classes/class_streampeer.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/4.0/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/4.0/doc/classes/StreamPeer.xml.

.. _class_StreamPeer:

StreamPeer
==========

**Inherits:** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`

**Inherited By:** :ref:`StreamPeerBuffer<class_StreamPeerBuffer>`, :ref:`StreamPeerExtension<class_StreamPeerExtension>`, :ref:`StreamPeerGZIP<class_StreamPeerGZIP>`, :ref:`StreamPeerTCP<class_StreamPeerTCP>`, :ref:`StreamPeerTLS<class_StreamPeerTLS>`

Abstract base class for interacting with streams.

.. rst-class:: classref-introduction-group

Description
-----------

StreamPeer is an abstract base class mostly used for stream-based protocols (such as TCP). It provides an API for sending and receiving data through streams as raw data or strings.

\ **Note:** When exporting to Android, make sure to enable the ``INTERNET`` permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

.. rst-class:: classref-reftable-group

Properties
----------

.. table::
   :widths: auto

   +-------------------------+---------------------------------------------------------+-----------+
   | :ref:`bool<class_bool>` | :ref:`big_endian<class_StreamPeer_property_big_endian>` | ``false`` |
   +-------------------------+---------------------------------------------------------+-----------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_16<class_StreamPeer_method_get_16>` **(** **)**                                                                                   |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_32<class_StreamPeer_method_get_32>` **(** **)**                                                                                   |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_64<class_StreamPeer_method_get_64>` **(** **)**                                                                                   |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_8<class_StreamPeer_method_get_8>` **(** **)**                                                                                     |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_available_bytes<class_StreamPeer_method_get_available_bytes>` **(** **)** |const|                                                 |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Array<class_Array>`             | :ref:`get_data<class_StreamPeer_method_get_data>` **(** :ref:`int<class_int>` bytes **)**                                                   |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`             | :ref:`get_double<class_StreamPeer_method_get_double>` **(** **)**                                                                           |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`             | :ref:`get_float<class_StreamPeer_method_get_float>` **(** **)**                                                                             |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Array<class_Array>`             | :ref:`get_partial_data<class_StreamPeer_method_get_partial_data>` **(** :ref:`int<class_int>` bytes **)**                                   |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`String<class_String>`           | :ref:`get_string<class_StreamPeer_method_get_string>` **(** :ref:`int<class_int>` bytes=-1 **)**                                            |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_u16<class_StreamPeer_method_get_u16>` **(** **)**                                                                                 |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_u32<class_StreamPeer_method_get_u32>` **(** **)**                                                                                 |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_u64<class_StreamPeer_method_get_u64>` **(** **)**                                                                                 |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                 | :ref:`get_u8<class_StreamPeer_method_get_u8>` **(** **)**                                                                                   |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`String<class_String>`           | :ref:`get_utf8_string<class_StreamPeer_method_get_utf8_string>` **(** :ref:`int<class_int>` bytes=-1 **)**                                  |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Variant<class_Variant>`         | :ref:`get_var<class_StreamPeer_method_get_var>` **(** :ref:`bool<class_bool>` allow_objects=false **)**                                     |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_16<class_StreamPeer_method_put_16>` **(** :ref:`int<class_int>` value **)**                                                       |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_32<class_StreamPeer_method_put_32>` **(** :ref:`int<class_int>` value **)**                                                       |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_64<class_StreamPeer_method_put_64>` **(** :ref:`int<class_int>` value **)**                                                       |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_8<class_StreamPeer_method_put_8>` **(** :ref:`int<class_int>` value **)**                                                         |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Error<enum_@GlobalScope_Error>` | :ref:`put_data<class_StreamPeer_method_put_data>` **(** :ref:`PackedByteArray<class_PackedByteArray>` data **)**                            |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_double<class_StreamPeer_method_put_double>` **(** :ref:`float<class_float>` value **)**                                           |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_float<class_StreamPeer_method_put_float>` **(** :ref:`float<class_float>` value **)**                                             |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Array<class_Array>`             | :ref:`put_partial_data<class_StreamPeer_method_put_partial_data>` **(** :ref:`PackedByteArray<class_PackedByteArray>` data **)**            |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_string<class_StreamPeer_method_put_string>` **(** :ref:`String<class_String>` value **)**                                         |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_u16<class_StreamPeer_method_put_u16>` **(** :ref:`int<class_int>` value **)**                                                     |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_u32<class_StreamPeer_method_put_u32>` **(** :ref:`int<class_int>` value **)**                                                     |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_u64<class_StreamPeer_method_put_u64>` **(** :ref:`int<class_int>` value **)**                                                     |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_u8<class_StreamPeer_method_put_u8>` **(** :ref:`int<class_int>` value **)**                                                       |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_utf8_string<class_StreamPeer_method_put_utf8_string>` **(** :ref:`String<class_String>` value **)**                               |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                  | :ref:`put_var<class_StreamPeer_method_put_var>` **(** :ref:`Variant<class_Variant>` value, :ref:`bool<class_bool>` full_objects=false **)** |
   +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Property Descriptions
---------------------

.. _class_StreamPeer_property_big_endian:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **big_endian** = ``false``

.. rst-class:: classref-property-setget

- void **set_big_endian** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **is_big_endian_enabled** **(** **)**

If ``true``, this **StreamPeer** will using big-endian format for encoding and decoding.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Method Descriptions
-------------------

.. _class_StreamPeer_method_get_16:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_16** **(** **)**

Gets a signed 16-bit value from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_32:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_32** **(** **)**

Gets a signed 32-bit value from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_64:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_64** **(** **)**

Gets a signed 64-bit value from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_8:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_8** **(** **)**

Gets a signed byte from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_available_bytes:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_available_bytes** **(** **)** |const|

Returns the number of bytes this **StreamPeer** has available.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_data:

.. rst-class:: classref-method

:ref:`Array<class_Array>` **get_data** **(** :ref:`int<class_int>` bytes **)**

Returns a chunk data with the received bytes. The number of bytes to be received can be requested in the ``bytes`` argument. If not enough bytes are available, the function will block until the desired amount is received. This function returns two values, an :ref:`Error<enum_@GlobalScope_Error>` code and a data array.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_double:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_double** **(** **)**

Gets a double-precision float from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_float:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_float** **(** **)**

Gets a single-precision float from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_partial_data:

.. rst-class:: classref-method

:ref:`Array<class_Array>` **get_partial_data** **(** :ref:`int<class_int>` bytes **)**

Returns a chunk data with the received bytes. The number of bytes to be received can be requested in the "bytes" argument. If not enough bytes are available, the function will return how many were actually received. This function returns two values, an :ref:`Error<enum_@GlobalScope_Error>` code, and a data array.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_string:

.. rst-class:: classref-method

:ref:`String<class_String>` **get_string** **(** :ref:`int<class_int>` bytes=-1 **)**

Gets an ASCII string with byte-length ``bytes`` from the stream. If ``bytes`` is negative (default) the length will be read from the stream using the reverse process of :ref:`put_string<class_StreamPeer_method_put_string>`.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_u16:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_u16** **(** **)**

Gets an unsigned 16-bit value from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_u32:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_u32** **(** **)**

Gets an unsigned 32-bit value from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_u64:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_u64** **(** **)**

Gets an unsigned 64-bit value from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_u8:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_u8** **(** **)**

Gets an unsigned byte from the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_utf8_string:

.. rst-class:: classref-method

:ref:`String<class_String>` **get_utf8_string** **(** :ref:`int<class_int>` bytes=-1 **)**

Gets a UTF-8 string with byte-length ``bytes`` from the stream (this decodes the string sent as UTF-8). If ``bytes`` is negative (default) the length will be read from the stream using the reverse process of :ref:`put_utf8_string<class_StreamPeer_method_put_utf8_string>`.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_get_var:

.. rst-class:: classref-method

:ref:`Variant<class_Variant>` **get_var** **(** :ref:`bool<class_bool>` allow_objects=false **)**

Gets a Variant from the stream. If ``allow_objects`` is ``true``, decoding objects is allowed.

Internally, this uses the same decoding mechanism as the :ref:`@GlobalScope.bytes_to_var<class_@GlobalScope_method_bytes_to_var>` method.

\ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_16:

.. rst-class:: classref-method

void **put_16** **(** :ref:`int<class_int>` value **)**

Puts a signed 16-bit value into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_32:

.. rst-class:: classref-method

void **put_32** **(** :ref:`int<class_int>` value **)**

Puts a signed 32-bit value into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_64:

.. rst-class:: classref-method

void **put_64** **(** :ref:`int<class_int>` value **)**

Puts a signed 64-bit value into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_8:

.. rst-class:: classref-method

void **put_8** **(** :ref:`int<class_int>` value **)**

Puts a signed byte into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_data:

.. rst-class:: classref-method

:ref:`Error<enum_@GlobalScope_Error>` **put_data** **(** :ref:`PackedByteArray<class_PackedByteArray>` data **)**

Sends a chunk of data through the connection, blocking if necessary until the data is done sending. This function returns an :ref:`Error<enum_@GlobalScope_Error>` code.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_double:

.. rst-class:: classref-method

void **put_double** **(** :ref:`float<class_float>` value **)**

Puts a double-precision float into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_float:

.. rst-class:: classref-method

void **put_float** **(** :ref:`float<class_float>` value **)**

Puts a single-precision float into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_partial_data:

.. rst-class:: classref-method

:ref:`Array<class_Array>` **put_partial_data** **(** :ref:`PackedByteArray<class_PackedByteArray>` data **)**

Sends a chunk of data through the connection. If all the data could not be sent at once, only part of it will. This function returns two values, an :ref:`Error<enum_@GlobalScope_Error>` code and an integer, describing how much data was actually sent.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_string:

.. rst-class:: classref-method

void **put_string** **(** :ref:`String<class_String>` value **)**

Puts a zero-terminated ASCII string into the stream prepended by a 32-bit unsigned integer representing its size.

\ **Note:** To put an ASCII string without prepending its size, you can use :ref:`put_data<class_StreamPeer_method_put_data>`:


.. tabs::

 .. code-tab:: gdscript

    put_data("Hello world".to_ascii_buffer())

 .. code-tab:: csharp

    PutData("Hello World".ToAsciiBuffer());



.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_u16:

.. rst-class:: classref-method

void **put_u16** **(** :ref:`int<class_int>` value **)**

Puts an unsigned 16-bit value into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_u32:

.. rst-class:: classref-method

void **put_u32** **(** :ref:`int<class_int>` value **)**

Puts an unsigned 32-bit value into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_u64:

.. rst-class:: classref-method

void **put_u64** **(** :ref:`int<class_int>` value **)**

Puts an unsigned 64-bit value into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_u8:

.. rst-class:: classref-method

void **put_u8** **(** :ref:`int<class_int>` value **)**

Puts an unsigned byte into the stream.

.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_utf8_string:

.. rst-class:: classref-method

void **put_utf8_string** **(** :ref:`String<class_String>` value **)**

Puts a zero-terminated UTF-8 string into the stream prepended by a 32 bits unsigned integer representing its size.

\ **Note:** To put a UTF-8 string without prepending its size, you can use :ref:`put_data<class_StreamPeer_method_put_data>`:


.. tabs::

 .. code-tab:: gdscript

    put_data("Hello world".to_utf8_buffer())

 .. code-tab:: csharp

    PutData("Hello World".ToUtf8Buffer());



.. rst-class:: classref-item-separator

----

.. _class_StreamPeer_method_put_var:

.. rst-class:: classref-method

void **put_var** **(** :ref:`Variant<class_Variant>` value, :ref:`bool<class_bool>` full_objects=false **)**

Puts a Variant into the stream. If ``full_objects`` is ``true`` encoding objects is allowed (and can potentially include code).

Internally, this uses the same encoding mechanism as the :ref:`@GlobalScope.var_to_bytes<class_@GlobalScope_method_var_to_bytes>` method.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`