Godot
/
godot-docs
mirror of https://github.com/godotengine/godot-docs.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
							:github_url: hide

.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the WebSocketServer.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_WebSocketServer:

WebSocketServer
===============

**Inherits:** :ref:`WebSocketMultiplayerPeer<class_WebSocketMultiplayerPeer>` **<** :ref:`MultiplayerPeer<class_MultiplayerPeer>` **<** :ref:`PacketPeer<class_PacketPeer>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`

A WebSocket server implementation.

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

This class implements a WebSocket server that can also support the high-level multiplayer API.

After starting the server (:ref:`listen<class_WebSocketServer_method_listen>`), you will need to :ref:`MultiplayerPeer.poll<class_MultiplayerPeer_method_poll>` it at regular intervals (e.g. inside :ref:`Node._process<class_Node_method__process>`). When clients connect, disconnect, or send data, you will receive the appropriate signal.

\ **Note:** Not available in HTML5 exports.

\ **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.

Properties
----------

+-----------------------------------------------+----------------------------------------------------------------------------+---------+
| :ref:`String<class_String>`                   | :ref:`bind_ip<class_WebSocketServer_property_bind_ip>`                     | ``"*"`` |
+-----------------------------------------------+----------------------------------------------------------------------------+---------+
| :ref:`X509Certificate<class_X509Certificate>` | :ref:`ca_chain<class_WebSocketServer_property_ca_chain>`                   |         |
+-----------------------------------------------+----------------------------------------------------------------------------+---------+
| :ref:`float<class_float>`                     | :ref:`handshake_timeout<class_WebSocketServer_property_handshake_timeout>` | ``3.0`` |
+-----------------------------------------------+----------------------------------------------------------------------------+---------+
| :ref:`CryptoKey<class_CryptoKey>`             | :ref:`private_key<class_WebSocketServer_property_private_key>`             |         |
+-----------------------------------------------+----------------------------------------------------------------------------+---------+
| :ref:`X509Certificate<class_X509Certificate>` | :ref:`ssl_certificate<class_WebSocketServer_property_ssl_certificate>`     |         |
+-----------------------------------------------+----------------------------------------------------------------------------+---------+

Methods
-------

+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                  | :ref:`disconnect_peer<class_WebSocketServer_method_disconnect_peer>` **(** :ref:`int<class_int>` id, :ref:`int<class_int>` code=1000, :ref:`String<class_String>` reason="" **)**                                   |
+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>`           | :ref:`get_peer_address<class_WebSocketServer_method_get_peer_address>` **(** :ref:`int<class_int>` id **)** |const|                                                                                                 |
+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                 | :ref:`get_peer_port<class_WebSocketServer_method_get_peer_port>` **(** :ref:`int<class_int>` id **)** |const|                                                                                                       |
+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`               | :ref:`has_peer<class_WebSocketServer_method_has_peer>` **(** :ref:`int<class_int>` id **)** |const|                                                                                                                 |
+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`               | :ref:`is_listening<class_WebSocketServer_method_is_listening>` **(** **)** |const|                                                                                                                                  |
+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`listen<class_WebSocketServer_method_listen>` **(** :ref:`int<class_int>` port, :ref:`PackedStringArray<class_PackedStringArray>` protocols=PackedStringArray(), :ref:`bool<class_bool>` gd_mp_api=false **)** |
+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                  | :ref:`stop<class_WebSocketServer_method_stop>` **(** **)**                                                                                                                                                          |
+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_WebSocketServer_signal_client_close_request:

- **client_close_request** **(** :ref:`int<class_int>` id, :ref:`int<class_int>` code, :ref:`String<class_String>` reason **)**

Emitted when a client requests a clean close. You should keep polling until you get a :ref:`client_disconnected<class_WebSocketServer_signal_client_disconnected>` signal with the same ``id`` to achieve the clean close. See :ref:`WebSocketPeer.close<class_WebSocketPeer_method_close>` for more details.

----

.. _class_WebSocketServer_signal_client_connected:

- **client_connected** **(** :ref:`int<class_int>` id, :ref:`String<class_String>` protocol, :ref:`String<class_String>` resource_name **)**

Emitted when a new client connects. "protocol" will be the sub-protocol agreed with the client, and "resource_name" will be the resource name of the URI the peer used.

"resource_name" is a path (at the very least a single forward slash) and potentially a query string.

----

.. _class_WebSocketServer_signal_client_disconnected:

- **client_disconnected** **(** :ref:`int<class_int>` id, :ref:`bool<class_bool>` was_clean_close **)**

Emitted when a client disconnects. ``was_clean_close`` will be ``true`` if the connection was shutdown cleanly.

----

.. _class_WebSocketServer_signal_data_received:

- **data_received** **(** :ref:`int<class_int>` id **)**

Emitted when a new message is received.

\ **Note:** This signal is *not* emitted when used as high-level multiplayer peer.

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

.. _class_WebSocketServer_property_bind_ip:

- :ref:`String<class_String>` **bind_ip**

+-----------+--------------------+
| *Default* | ``"*"``            |
+-----------+--------------------+
| *Setter*  | set_bind_ip(value) |
+-----------+--------------------+
| *Getter*  | get_bind_ip()      |
+-----------+--------------------+

When not set to ``*`` will restrict incoming connections to the specified IP address. Setting ``bind_ip`` to ``127.0.0.1`` will cause the server to listen only to the local host.

----

.. _class_WebSocketServer_property_ca_chain:

- :ref:`X509Certificate<class_X509Certificate>` **ca_chain**

+----------+---------------------+
| *Setter* | set_ca_chain(value) |
+----------+---------------------+
| *Getter* | get_ca_chain()      |
+----------+---------------------+

When using SSL (see :ref:`private_key<class_WebSocketServer_property_private_key>` and :ref:`ssl_certificate<class_WebSocketServer_property_ssl_certificate>`), you can set this to a valid :ref:`X509Certificate<class_X509Certificate>` to be provided as additional CA chain information during the SSL handshake.

----

.. _class_WebSocketServer_property_handshake_timeout:

- :ref:`float<class_float>` **handshake_timeout**

+-----------+------------------------------+
| *Default* | ``3.0``                      |
+-----------+------------------------------+
| *Setter*  | set_handshake_timeout(value) |
+-----------+------------------------------+
| *Getter*  | get_handshake_timeout()      |
+-----------+------------------------------+

The time in seconds before a pending client (i.e. a client that has not yet finished the HTTP handshake) is considered stale and forcefully disconnected.

----

.. _class_WebSocketServer_property_private_key:

- :ref:`CryptoKey<class_CryptoKey>` **private_key**

+----------+------------------------+
| *Setter* | set_private_key(value) |
+----------+------------------------+
| *Getter* | get_private_key()      |
+----------+------------------------+

When set to a valid :ref:`CryptoKey<class_CryptoKey>` (along with :ref:`ssl_certificate<class_WebSocketServer_property_ssl_certificate>`) will cause the server to require SSL instead of regular TCP (i.e. the ``wss://`` protocol).

----

.. _class_WebSocketServer_property_ssl_certificate:

- :ref:`X509Certificate<class_X509Certificate>` **ssl_certificate**

+----------+----------------------------+
| *Setter* | set_ssl_certificate(value) |
+----------+----------------------------+
| *Getter* | get_ssl_certificate()      |
+----------+----------------------------+

When set to a valid :ref:`X509Certificate<class_X509Certificate>` (along with :ref:`private_key<class_WebSocketServer_property_private_key>`) will cause the server to require SSL instead of regular TCP (i.e. the ``wss://`` protocol).

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

.. _class_WebSocketServer_method_disconnect_peer:

- void **disconnect_peer** **(** :ref:`int<class_int>` id, :ref:`int<class_int>` code=1000, :ref:`String<class_String>` reason="" **)**

Disconnects the peer identified by ``id`` from the server. See :ref:`WebSocketPeer.close<class_WebSocketPeer_method_close>` for more information.

----

.. _class_WebSocketServer_method_get_peer_address:

- :ref:`String<class_String>` **get_peer_address** **(** :ref:`int<class_int>` id **)** |const|

Returns the IP address of the given peer.

----

.. _class_WebSocketServer_method_get_peer_port:

- :ref:`int<class_int>` **get_peer_port** **(** :ref:`int<class_int>` id **)** |const|

Returns the remote port of the given peer.

----

.. _class_WebSocketServer_method_has_peer:

- :ref:`bool<class_bool>` **has_peer** **(** :ref:`int<class_int>` id **)** |const|

Returns ``true`` if a peer with the given ID is connected.

----

.. _class_WebSocketServer_method_is_listening:

- :ref:`bool<class_bool>` **is_listening** **(** **)** |const|

Returns ``true`` if the server is actively listening on a port.

----

.. _class_WebSocketServer_method_listen:

- :ref:`Error<enum_@GlobalScope_Error>` **listen** **(** :ref:`int<class_int>` port, :ref:`PackedStringArray<class_PackedStringArray>` protocols=PackedStringArray(), :ref:`bool<class_bool>` gd_mp_api=false **)**

Starts listening on the given port.

You can specify the desired subprotocols via the "protocols" array. If the list empty (default), no sub-protocol will be requested.

If ``true`` is passed as ``gd_mp_api``, the server will behave like a multiplayer peer for the :ref:`MultiplayerAPI<class_MultiplayerAPI>`, connections from non-Godot clients will not work, and :ref:`data_received<class_WebSocketServer_signal_data_received>` will not be emitted.

If ``false`` is passed instead (default), you must call :ref:`PacketPeer<class_PacketPeer>` functions (``put_packet``, ``get_packet``, etc.), on the :ref:`WebSocketPeer<class_WebSocketPeer>` returned via ``get_peer(id)`` to communicate with the peer with given ``id`` (e.g. ``get_peer(id).get_available_packet_count``).

----

.. _class_WebSocketServer_method_stop:

- void **stop** **(** **)**

Stops the server and clear its state.

.. |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.)`