diff options
Diffstat (limited to 'docs/library/usocket.rst')
| -rw-r--r-- | docs/library/usocket.rst | 59 |
1 files changed, 53 insertions, 6 deletions
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index dfdcd68bc..fab05b652 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -68,7 +68,16 @@ Functions .. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP) - Create a new socket using the given address family, socket type and protocol number. + Create a new socket using the given address family, socket type and + protocol number. Note that specifying *proto* in most cases is not + required (and not recommended, as some MicroPython ports may omit + ``IPPROTO_*`` constants). Instead, *type* argument will select needed + protocol automatically:: + + # Create STREAM TCP socket + socket(AF_INET, SOCK_STREAM) + # Create DGRAM UDP socket + socket(AF_INET, SOCK_DGRAM) .. function:: getaddrinfo(host, port) @@ -80,8 +89,8 @@ Functions The following example shows how to connect to a given url:: - s = socket.socket() - s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1]) + s = usocket.socket() + s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1]) .. admonition:: Difference to CPython :class: attention @@ -96,13 +105,29 @@ Functions from an exception object). The use of negative values is a provisional detail which may change in the future. +.. function:: inet_ntop(af, bin_addr) + + Convert a binary network address *bin_addr* of the given address family *af* + to a textual representation:: + + >>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1") + '127.0.0.1' + +.. function:: inet_pton(af, txt_addr) + + Convert a textual network address *txt_addr* of the given address family *af* + to a binary representation:: + + >>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4") + b'\x01\x02\x03\x04' + Constants --------- .. data:: AF_INET AF_INET6 - Address family types. Availability depends on a particular board. + Address family types. Availability depends on a particular `MicroPython port`. .. data:: SOCK_STREAM SOCK_DGRAM @@ -112,7 +137,11 @@ Constants .. data:: IPPROTO_UDP IPPROTO_TCP - IP protocol numbers. + IP protocol numbers. Availability depends on a particular `MicroPython port`. + Note that you don't need to specify these in a call to `usocket.socket()`, + because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and + `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants + is as an argument to `setsockopt()`. .. data:: usocket.SOL_* @@ -208,12 +237,30 @@ Methods .. method:: socket.settimeout(value) + **Note**: Not every port supports this method, see below. + Set a timeout on blocking socket operations. The value argument can be a nonnegative floating point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations will raise an `OSError` exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode. + Not every `MicroPython port` supports this method. A more portable and + generic solution is to use `uselect.poll` object. This allows to wait on + multiple objects at the same time (and not just on sockets, but on generic + stream objects which support polling). Example:: + + # Instead of: + s.settimeout(1.0) # time in seconds + s.read(10) # may timeout + + # Use: + poller = uselect.poll() + poller.register(s, uselect.POLLIN) + res = poller.poll(1000) # time in milliseconds + if not res: + # s is still not ready for input, i.e. operation timed out + .. admonition:: Difference to CPython :class: attention @@ -281,7 +328,7 @@ Methods Return value: number of bytes written. -.. exception:: socket.error +.. exception:: usocket.error MicroPython does NOT have this exception. |