docs/usocket: getaddrinfo: Describe af/type/proto optional params.

These can be optionally specified, but all ports are expected to be able to
accept them, at the very least ignore, though handling of "type" param
(SOCK_STREAM vs SOCK_DGRAM) is recommended.
This commit is contained in:
Paul Sokolovsky 2018-01-27 12:54:16 +02:00 committed by Damien George
parent 12fde67a25
commit 2e3468a68c
1 changed files with 17 additions and 3 deletions

View File

@ -79,19 +79,33 @@ Functions
# Create DGRAM UDP socket # Create DGRAM UDP socket
socket(AF_INET, SOCK_DGRAM) socket(AF_INET, SOCK_DGRAM)
.. function:: getaddrinfo(host, port) .. function:: getaddrinfo(host, port, af=0, type=0, proto=0, flags=0)
Translate the host/port argument into a sequence of 5-tuples that contain all the Translate the host/port argument into a sequence of 5-tuples that contain all the
necessary arguments for creating a socket connected to that service. The list of necessary arguments for creating a socket connected to that service. Arguments
5-tuples has following structure:: *af*, *type*, and *proto* (which have the same meaning as for `socket()` function)
can be used to filter which kind of addresses are returned. If a parameter not
specified or zero, all combinations of addresses can be returned (requiring
filtering on the user side).
The resulting list of 5-tuples has the following structure::
(family, type, proto, canonname, sockaddr) (family, type, proto, canonname, sockaddr)
The following example shows how to connect to a given url:: The following example shows how to connect to a given url::
s = usocket.socket() s = usocket.socket()
# This assumes that if "type" is not specified, address for
# SOCK_STREAM will be returned, which may be not true
s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1]) s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1])
Recommended use of filtering params::
s = usocket.socket()
# Guaranteedly returns address which can be connect'ed to for
# stream operation.
s.connect(usocket.getaddrinfo('www.micropython.org', 80, 0, SOCK_STREAM)[0][-1])
.. admonition:: Difference to CPython .. admonition:: Difference to CPython
:class: attention :class: attention