Network
=======
.. module:: sfml.network
.. contents:: :local:

IpAddress
^^^^^^^^^

.. class:: IpAddress()

   Encapsulate an IPv4 network address.

   :class:`IpAddress` is an utility class for manipulating network
   addresses.

   It provides a set of class methods and conversion attributes to
   easily build or transform an IP address from/to various
   representations.

   Usage example::

      ip0 = sf.IpAddress()                             # an invalid address
      ip1 = sf.IpAddress.NONE                          # an invalid address (same as ip0)
      ip2 = sf.IpAddress.from_string("127.0.0.1")      # the local host address
      ip3 = sf.IpAddress.BROADCAST                     # the broadcast address
      ip4 = sf.IpAddress.from_bytes(192, 168, 1, 56)   # a local address
      ip5 = sf.IpAddress.from_string("my_computer")    # a local address created from a network name
      ip6 = sf.IpAddress.from_string("89.54.1.169")    # a distant address
      ip7 = sf.IpAddress.from_string("www.google.com") # a distant address created from a network name
      ip8 = sf.IpAddress.get_local_address()           # my address on the local network
      ip9 = sf.IpAddress.get_public_address()          # my address on the internet

   Note that :class:`IpAddress` currently doesn't support IPv6 nor
   other types of network addresses.

   .. py:data:: NONE

      Value representing an empty/invalid address.

   .. py:data:: LOCAL_HOST

      The "localhost" address (for connecting a computer to itself
      locally)

   .. py:data:: BROADCAST

      The "broadcast" address (for sending UDP messages to everyone on
      a local network)

   .. classmethod:: from_string(string)

      Construct the address from a string.

      Here address can be either a decimal address (ex: "192.168.1.56")
      or a network name (ex: "localhost").

      :param str string: IP address or network name
      :rtype: :class:`sfml.network.IpAddress`

   .. classmethod:: from_integer(integer)

      Construct the address from an integer.

      This constructor uses the internal representation of the address
      directly. It should be used for optimization purposes, and only
      if you got that representation from :attr:`IpAddress.integer`.

      :param integer integer: 4 bytes of the address packed into a 32-bits integer
      :rtype: :class:`sfml.network.IpAddress`

   .. classmethod:: from_bytes(b0, b1, b2, b3)

      Construct the address from 4 bytes.

      Calling IpAddress.from_bytes(a, b, c, d) is equivalent to calling
      IpAddress.from_string("a.b.c.d"), but safer as it doesn't have to
      parse a string to get the address components.

      :param integer b0: First byte of the address
      :param integer b1: Second byte of the address
      :param integer b2: Third byte of the address
      :param integer b3: Fourth byte of the address
      :rtype: sfml.network.IpAddress

   .. attribute:: string

      Get a string representation of the address.

      The returned string is the decimal representation of the IP
      address (like "192.168.1.56"), even if it was constructed from a
      host name.

      :type: string

   .. attribute:: integer

      Get an integer representation of the address.

      The returned number is the internal representation of the
      address, and should be used for optimization purposes only (like
      sending the address through a socket). The integer produced by
      this function can then be converted back to a
      :class:`IpAddress` with the proper constructor.

      :type: integer

   .. classmethod:: get_local_address()

      Get the computer's local address.

      The local address is the address of the computer from the LAN
      point of view, i.e. something like 192.168.1.56. It is meaningful
      only for communications over the local network. Unlike
      :func:`get_public_address`, this function is fast and may be used
      safely anywhere.

      :rtype: :class:`sfml.network.IpAddress`

   .. classmethod:: get_public_address([timeout])

      Get the computer's public address.

      The public address is the address of the computer from the
      internet point of view, i.e. something like 89.54.1.169. It is
      necessary for communications over the world wide web. The only
      way to get a public address is to ask it to a distant website; as
      a consequence, this function depends on both your network
      connection and the server, and may be very slow. You should use
      it as few as possible. Because this function depends on the
      network connection and on a distant server, you may use a time
      limit if you don't want your program to be possibly stuck waiting
      in case there is a problem; this limit is deactivated by default.

      :param sfml.system.Time timeout: Maximum time to wait
      :rtype: :class:`sfml.network.IpAddress`

SocketException
^^^^^^^^^^^^^^^
.. py:exception:: SocketException(Exception)

   Main exception defined for all socket exceptions. Most of socket's
   method can potentially raise one of the three following exceptions
   and you'll use this one to catch any of them in one except statement.

.. py:exception:: SocketDisconnected(SocketException)

   In **blocking mode**, the socket may raise this exception to warm
   you it has been disconnected.

.. py:exception:: SocketNotReady(SocketException)

   In **non-blocking mode**, the socket will raise this exception if
   the socket is not ready to send/receive data yet.

.. py:exception:: SocketError(SocketException)

   In ** blocking mode**, the socket may raise this exception to warm
   you an unexpected error happened.


Socket
^^^^^^

.. py:class:: Socket()

      Base class for all the socket types.

      This class mainly defines internal stuff to be used by derived
      classes.

      The only public features that it defines, and which is therefore
      common to all the socket classes, is the blocking state.
      All sockets can be set as blocking or non-blocking.

      In blocking mode, socket functions will hang until the operation
      completes, which means that the entire program (well, in fact the
      current thread if you use multiple ones) will be stuck waiting
      for your socket operation to complete.

      In non-blocking mode, all the socket functions will return
      immediately. If the socket is not ready to complete the requested
      operation, the function simply raises the exception :exc:`SocketNotReady`.

      The default mode, which is blocking, is the one that is generally
      used, in combination with threads or selectors. The non-blocking
      mode is rather used in real-time applications that run an endless
      loop that can poll the socket often enough, and cannot afford
      blocking this loop.

   .. py:data:: DONE

      The socket has sent / received the data.

   .. py:data:: NOT_READY

      The socket is not ready to send / receive data yet.

   .. py:data:: DISCONNECTED

      The TCP socket has been disconnected.

   .. py:data:: ERROR

      An unexpected error happened.

   .. py:data:: ANY_PORT

      Special value that tells the system to pick any available port.

   .. py:attribute:: blocking

         The socket's blocking state; blocking or non-blocking.

      :type: bool


TcpSocket
^^^^^^^^^

.. py:class:: TcpSocket(Socket)

      Specialized socket using the TCP protocol.

      TCP is a connected protocol, which means that a TCP socket can
      only communicate with the host it is connected to.

      It can't send or receive anything if it is not connected.

      The TCP protocol is reliable but adds a slight overhead. It
      ensures that your data will always be received in order and
      without errors (no data corrupted, lost or duplicated).

      When a socket is connected to a remote host, you can retrieve
      informations about this host with the :attr:`remote_address` and
      :attr:`remote_port` attributes. You can also get the local port
      to which the socket is bound (which is automatically chosen when
      the socket is connected), with the :attr:`local_port` attribute.

      Sending and receiving data can use only the low-level functions.
      The low-level functions process a raw sequence of bytes,
      and cannot ensure that one call to :func:`send` will exactly
      match one call to :func:`receive` at the other end of the socket.

      The high-level interface is not implemented yet.

      The socket is automatically disconnected when it is destroyed,
      but if you want to explicitly close the connection while the
      socket instance is still alive, you can call disconnect.

      Usage example::

         # --- the client ---
         # create a socket and connect it to 192.168.1.50 on port 55001
         socket = sf.TcpSocket()
         socket.connect(sf.IpAddress.from_string("192.168.1.50"), 55001)


         # send a message to the connected host
         message = "Hi, I am a client".encode('utf-8')
         socket.send(message)

         # receive an answer from the server
         answer = socket.receive(1024)
         print("The server said: {0}".format(answer.decode('utf-8')))


         # --- the server ---
         # create a listener to wait for incoming connections on port 55001
         listener = sf.TcpListener()
         listener.listen(55001)

         # wait for a connection
         socket = listener.accept(socket)
         print("New client connected: {0}".format(socket.remote_address))

         # receive a message from the client
         message = socket.receive(1024)
         print("The client said: {0}".format(message.decode('utf-8')))

         # send an answer
         socket.send("Welcome, client".encode('utf-8'))

   .. py:attribute:: local_port

      The port to which the socket is bound locally.

      If the socket is not connected, its value is 0.

      :type: integer

   .. py:attribute:: remote_address

      The address of the connected peer.

      It the socket is not connected, its value
      :const:`IpAddress.NONE`.

      :type: :class:`sfml.network.IpAddress`

   .. py:attribute:: remote_port

      The port of the connected peer to which the socket is connected.

      If the socket is not connected, its value is 0.

      :type: integer

   .. py:method:: connect(remote_address, remote_port[, timeout])

      Connect the socket to a remote peer.

      In blocking mode, this function may take a while, especially if
      the remote peer is not reachable. The last parameter allows you
      to stop trying to connect after a given timeout. If the socket
      was previously connected, it is first disconnected.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :param sfml.network.IpAddress remote_address: Address of the remote peer
      :param integer remote_port: Port of the remote peer
      :param sfml.system.Time timeout: Optional maximum time to wait

   .. py:method:: disconnect()

      Disconnect the socket from its remote peer.

      This function gracefully closes the connection. If the socket is
      not connected, this function has no effect.

   .. py:method:: send(data)

      Send raw data to the remote peer.

      This function will fail if the socket is not connected.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :param bytes data: The sequence of bytes to send

   .. py:method:: receive(size)

      Receive raw data from the remote peer.

      In blocking mode, this function will wait until some bytes are
      actually received. This function will fail if the socket is not
      connected.

      .. note::

         The received data's length may be different from the asked length.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :param integer size: Maximum number of bytes that can be received
      :return: A sequence of bytes
      :rtype: bytes


UdpSocket
^^^^^^^^^

.. py:class:: UdpSocket(Socket)

   Specialized socket using the UDP protocol.

   A UDP socket is a connectionless socket.

   Instead of connecting once to a remote host, like TCP sockets, it
   can send to and receive from any host at any time.

   It is a datagram protocol: bounded blocks of data (datagrams) are
   transferred over the network rather than a continuous stream of data
   (TCP). Therefore, one call to send will always match one call to
   receive (if the datagram is not lost), with the same data that was
   sent.

   The UDP protocol is lightweight but unreliable. Unreliable means
   that datagrams may be duplicated, be lost or arrive reordered.
   However, if a datagram arrives, its data is guaranteed to be valid.

   UDP is generally used for real-time communication (audio or video
   streaming, real-time games, etc.) where speed is crucial and lost
   data doesn't matter much.

   Sending and receiving data can only use the low-level functions. The
   low-level functions process a raw sequence of bytes. The high-level
   method is not implemented.

   It is important to note that :class:`UdpSocket` is unable to send
   datagrams bigger than :attr:`MAX_DATAGRAM_SIZE`. In this case, it
   returns an error and doesn't send anything.

   If the socket is bound to a port, it is automatically unbound from
   it when the socket is destroyed. However, you can unbind the socket
   explicitly with the :func:`unbind` function if necessary, to stop
   receiving messages or make the port available for other sockets.

   Usage example::

      # --- the client ---
      # create a socket and bind it to the port 55001
      socket = sf.UdpSocket()
      socket.bind(55001)

      # send a message to 192.168.1.50 on port 55002
      message = "Hi, I am {0}".format(sf.IpAddress.get_local_address().string)
      socket.send(message.encode('utf-8'), sf.IpAddress.from_string("192.168.1.50"), 55002)

      # receive an answer (most likely from 192.168.1.50, but could be anyone else)
      answer, sender, port = socket.receive(1024)
      print("{0} said: {1}".format(sender.string, answer.decode('utf-8')))

      # --- the server ---
      # create a socket and bind it to the port 55002
      socket = sf.UdpSocket()
      socket.bind(55002)

      # receive a message from anyone
      message, sender, port = socket.receive(1024)
      print("{0} said: {1}".format(ip.string, message.decode('utf-8')))

      # send an answer
      answer = "Welcome {0}".format(sender.string)
      socket.send(answer, sender, port)

   .. py:data:: MAX_DATAGRAM_SIZE

      The maximum number of bytes that can be sent in a single UDP datagram.

   .. py:attribute:: local_port

      The port to which the socket is bound locally.

      If the socket is not connected, its value is 0.

      :type: integer

   .. py:method:: bind(port)

      Bind the socket to a specific port.

      Binding the socket to a port is necessary for being able to
      receive data on that port. You can use the special value
      :attr:`Socket.ANY_PORT` to tell the system to automatically pick an
      available port, and then get the chosen port via the attribute
      local_port.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :param integer port: Port to bind the socket to

   .. py:method:: unbind()

      Unbind the socket from the local port to which it is bound.

      The port that the socket was previously using is immediately
      available after this function is called. If the socket is not
      bound to a port, this function has no effect.

   .. py:method:: send(data, remote_address, port)

      Send raw data to a remote peer.

      Make sure that size is not greater than
      :attr:`MAX_DATAGRAM_SIZE`, otherwise this function will
      fail and no data will be sent.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :param bytes data: The sequence of bytes to send
      :param sfml.network.IpAddress remote_address: Address of the receiver
      :param integer port: Port of the receiver to send the data to

   .. py:method:: receive(size)

      Receive raw data from a remote peer.

      In blocking mode, this function will wait until some bytes are
      actually received. Be careful to use a buffer which is large
      enough for the data that you intend to receive, if it is too
      small then an error will be returned and *all* the data will
      be lost.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :param integer size: Maximum number of bytes that can be received
      :return: A tuple with the sequence of bytes received, the remote address and the port used.
      :rtype: tuple (bytes, sfml.network.IpAddress, integer)


TcpListener
^^^^^^^^^^^

.. py:class:: TcpListener(Socket)

   :class:`Socket` that listens to new TCP connections.

   A listener socket is a special type of socket that listens to a
   given port and waits for connections on that port.

   This is all it can do.

   When a new connection is received, you must call accept and the
   listener returns a new instance of :class:`TcpSocket` that is
   properly initialized and can be used to communicate with the new
   client.

   Listener sockets are specific to the TCP protocol, UDP sockets are
   connectionless and can therefore communicate directly. As a
   consequence, a listener socket will always return the new
   connections as :class:`TcpSocket` instances.

   A listener is automatically closed on destruction, like all other
   types of socket. However if you want to stop listening before the
   socket is destroyed, you can call its :func:`close()` function.

   Usage example::

      # create a listener socket and make it wait for new connections on port 55001
      listener = sf.TcpListener()
      listener.listen(55001)

      # endless loop that waits for new connections
      while running:
         try:
            client = listener.accept()

         except sf.SocketException as error:
            print("An error occurred! Error: {0}".format(error))
            exit(1)

         # a new client just connected!
         print("New connection received from {0}".format(client.remote_address))
         do_something_with(client)

   .. py:attribute:: local_port

      The port to which the socket is bound locally.

      If the socket is not listening to a port, its value is 0.

      :type: integer

   .. py:method:: listen(port)

      Start listening for connections.

      This functions makes the socket listen to the specified port,
      waiting for new connections. If the socket was previously
      listening to another port, it will be stopped first and bound to
      the new port.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :param integer port: Port to listen for new connections

   .. py:method:: close()

      Stop listening and close the socket.

      This function gracefully stops the listener. If the socket is not
      listening, this function has no effect.

   .. py:method:: accept()

      Accept a new connection.

      If the socket is in blocking mode, this function will not return
      until a connection is actually received.

      :raise: :exc:`SocketDisconnected`, :exc:`SocketNotReady` or :exc:`SocketError`
      :return: :class:`Socket` that holds the new connection
      :rtype: :class:`sfml.network.TcpSocket`