From 2e3468a68c842136b14d396886c03e0f182ea03c Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 27 Jan 2018 12:54:16 +0200 Subject: [PATCH] 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. --- docs/library/usocket.rst | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 3ae477a9ac..3c8f878f1a 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -79,19 +79,33 @@ Functions # Create DGRAM UDP socket 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 - necessary arguments for creating a socket connected to that service. The list of - 5-tuples has following structure:: + necessary arguments for creating a socket connected to that service. Arguments + *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) The following example shows how to connect to a given url:: 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]) + 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 :class: attention