From 705a84f5b8908b462a0c0c98b64d5d111ec20d17 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Wed, 15 Jul 2020 23:08:11 -0500 Subject: Change how address and socket are determined in Lirc This is to help with making this package cross-platform. --- docs/source/usage.rst | 57 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 9 deletions(-) (limited to 'docs/source/usage.rst') diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 588d2f7..ef9aa96 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -16,16 +16,16 @@ of things you can now import from it to get started. ) The most relevant of these is ``Lirc``, since this is the main class -you will be using. +you will be using. ``LircResponse`` is the response object that is returned +when you send a command. All the others are just errors. Initializing Lirc ----------------- -The ``Lirc`` class takes in three separate options, which all have default -values, that we may pass into it to construct it and override those default -values. - -The simplest way to construct ``Lirc`` is with no arguments at all. +The ``Lirc`` class takes in three separate options: ``address``, ``socket``, +and ``timeout``. These all have default values that depend on the operating +system you are on. So the simplest way to construct ``Lirc`` is with no +arguments at all. .. code-block:: python @@ -33,6 +33,45 @@ The simplest way to construct ``Lirc`` is with no arguments at all. lirc = Lirc() -This will attempt to connect to the lircd socket at "/var/run/lirc/lircd" on -your system, create a socket using ``AF_UNIX`` and ``SOCK_STREAM``, and sets -a socket timeout of 5 seconds. \ No newline at end of file +Overriding LIRC Defaults on Initialization +------------------------------------------ + +However, if we the defaults don't work for us? Let's say we're on Windows +and we want to connect over TCP to a remote LIRC server on another Windows +machine. So we've passed in an ``address`` to override the default so it doesn't +look for the daemon on the localhost. ``socket`` and ``timeout`` are passed in +just to show that we can, these are already the defaults on Windows. + +.. code-block:: python + + import socket + from lirc import Lirc + + lirc = Lirc( + address=("10.16.30.2", 8765), + socket=socket.socket(socket.AF_INET, socket.SOCK_STREAM), + timeout=5 + ) + +LIRC Initialization Defaults per Operating System +----------------------------------------------- + +From the options we may pass into ``Lirc``, ``address`` and ``socket`` will +change depending on the operating system you are using. The ``timeout`` always +defaults to 5 (seconds). + +On Linux, this will attempt to connect to the lircd socket at +``/var/run/lirc/lircd`` and create a socket using ``AF_UNIX`` and +``SOCK_STREAM``. + +On macOS, it will be almost identical to Linux except that all the paths +on macOS will be prefixed by ``/opt/local/`` so the connection to the lircd +socket will instead be at ``/opt/local/var/run/lirc/lircd``. The socket that +is created will be the same. + +However if we are on Windows, we can't use unix domain sockets. So instead, +WinLIRC uses TCP to communicate with the lirc daemon. So instead of a string +for the address, it defaults to a tuple of ("localhost", 8765), the default on +WinLIRC. The first part contains the address whereas the second is the port. +Furthermore, the socket that is created uses ``AF_INET`` and ``SOCK_STREAM`` +instead now. -- cgit v1.2.3