docs/library/usocket: Describe complete information on address formats.

Describe that the only portable way to deal with addresses is by using
getaddrinfo(). Describe that some ports may support tuple addresses using
"socket" module (vs "usocket" of native MicroPython).
This commit is contained in:
Paul Sokolovsky 2017-08-20 09:49:12 +03:00
parent ccaad53270
commit 3f91570483
1 changed files with 41 additions and 5 deletions

View File

@ -21,11 +21,47 @@ This module provides access to the BSD socket interface.
Socket address format(s)
------------------------
The functions below which expect a network address, accept it in the format of
*(ipv4_address, port)*, where *ipv4_address* is a string with dot-notation numeric
IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range
1-65535. Note the domain names are not accepted as *ipv4_address*, they should be
resolved first using `usocket.getaddrinfo()`.
The native socket address format of the ``usocket`` module is an opaque data type
returned by `getaddrinfo` function, which must be used to resolve textual address
(including numeric addresses)::
sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1]
# You must use getaddrinfo() even for numeric addresses
sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1]
# Now you can use that address
sock.connect(addr)
Using `getaddrinfo` is the most efficient (both in terms of memory and processing
power) and portable way to work with addresses.
However, ``socket`` module (note the difference with native MicroPython
``usocket`` module described here) provides CPython-compatible way to specify
addresses using tuples, as described below. Note that depending on a
`MicroPython port`, ``socket`` module can be builtin or need to be
installed from `micropython-lib` (as in the case of `MicroPython Unix port`),
and some ports still accept only numeric addresses in the tuple format,
and require to use `getaddrinfo` function to resolve domain names.
Summing up:
* Always use `getaddrinfo` when writing portable applications.
* Tuple addresses described below can be used as a shortcut for
quick hacks and interactive use, if your port supports them.
Tuple address format for ``socket`` module:
* IPv4: *(ipv4_address, port)*, where *ipv4_address* is a string with
dot-notation numeric IPv4 address, e.g. ``"8.8.8.8"``, and *port* is and
integer port number in the range 1-65535. Note the domain names are not
accepted as *ipv4_address*, they should be resolved first using
`usocket.getaddrinfo()`.
* IPv6: *(ipv6_address, port, flowinfo, scopeid)*, where *ipv6_address*
is a string with colon-notation numeric IPv6 address, e.g. ``"2001:db8::1"``,
and *port* is an integer port number in the range 1-65535. *flowinfo*
must be 0. *scopeid* is the interface scope identifier for link-local
addresses. Note the domain names are not accepted as *ipv6_address*,
they should be resolved first using `usocket.getaddrinfo()`. Availability
of IPv6 support depends on a `MicroPython port`.
Functions
---------