Cory McWilliams
79022e1e1f
git-svn-id: https://www.unprompted.com/svn/projects/tildefriends/trunk@3621 ed5197a5-7fde-0310-b194-c3ffbd925b24
109 lines
3.5 KiB
ReStructuredText
109 lines
3.5 KiB
ReStructuredText
|
|
.. _dns:
|
|
|
|
DNS utility functions
|
|
=====================
|
|
|
|
libuv provides asynchronous variants of `getaddrinfo` and `getnameinfo`.
|
|
|
|
|
|
Data types
|
|
----------
|
|
|
|
.. c:type:: uv_getaddrinfo_t
|
|
|
|
`getaddrinfo` request type.
|
|
|
|
.. c:type:: void (*uv_getaddrinfo_cb)(uv_getaddrinfo_t* req, int status, struct addrinfo* res)
|
|
|
|
Callback which will be called with the getaddrinfo request result once
|
|
complete. In case it was cancelled, `status` will have a value of
|
|
``UV_ECANCELED``.
|
|
|
|
.. c:type:: uv_getnameinfo_t
|
|
|
|
`getnameinfo` request type.
|
|
|
|
.. c:type:: void (*uv_getnameinfo_cb)(uv_getnameinfo_t* req, int status, const char* hostname, const char* service)
|
|
|
|
Callback which will be called with the getnameinfo request result once
|
|
complete. In case it was cancelled, `status` will have a value of
|
|
``UV_ECANCELED``.
|
|
|
|
|
|
Public members
|
|
^^^^^^^^^^^^^^
|
|
|
|
.. c:member:: uv_loop_t* uv_getaddrinfo_t.loop
|
|
|
|
Loop that started this getaddrinfo request and where completion will be
|
|
reported. Readonly.
|
|
|
|
.. c:member:: struct addrinfo* uv_getaddrinfo_t.addrinfo
|
|
|
|
Pointer to a `struct addrinfo` containing the result. Must be freed by the user
|
|
with :c:func:`uv_freeaddrinfo`.
|
|
|
|
.. versionchanged:: 1.3.0 the field is declared as public.
|
|
|
|
.. c:member:: uv_loop_t* uv_getnameinfo_t.loop
|
|
|
|
Loop that started this getnameinfo request and where completion will be
|
|
reported. Readonly.
|
|
|
|
.. c:member:: char[NI_MAXHOST] uv_getnameinfo_t.host
|
|
|
|
Char array containing the resulting host. It's null terminated.
|
|
|
|
.. versionchanged:: 1.3.0 the field is declared as public.
|
|
|
|
.. c:member:: char[NI_MAXSERV] uv_getnameinfo_t.service
|
|
|
|
Char array containing the resulting service. It's null terminated.
|
|
|
|
.. versionchanged:: 1.3.0 the field is declared as public.
|
|
|
|
.. seealso:: The :c:type:`uv_req_t` members also apply.
|
|
|
|
|
|
API
|
|
---
|
|
|
|
.. c:function:: int uv_getaddrinfo(uv_loop_t* loop, uv_getaddrinfo_t* req, uv_getaddrinfo_cb getaddrinfo_cb, const char* node, const char* service, const struct addrinfo* hints)
|
|
|
|
Asynchronous :man:`getaddrinfo(3)`.
|
|
|
|
Either node or service may be NULL but not both.
|
|
|
|
`hints` is a pointer to a struct addrinfo with additional address type
|
|
constraints, or NULL. Consult `man -s 3 getaddrinfo` for more details.
|
|
|
|
Returns 0 on success or an error code < 0 on failure. If successful, the
|
|
callback will get called sometime in the future with the lookup result,
|
|
which is either:
|
|
|
|
* status == 0, the res argument points to a valid `struct addrinfo`, or
|
|
* status < 0, the res argument is NULL. See the UV_EAI_* constants.
|
|
|
|
Call :c:func:`uv_freeaddrinfo` to free the addrinfo structure.
|
|
|
|
.. versionchanged:: 1.3.0 the callback parameter is now allowed to be NULL,
|
|
in which case the request will run **synchronously**.
|
|
|
|
.. c:function:: void uv_freeaddrinfo(struct addrinfo* ai)
|
|
|
|
Free the struct addrinfo. Passing NULL is allowed and is a no-op.
|
|
|
|
.. c:function:: int uv_getnameinfo(uv_loop_t* loop, uv_getnameinfo_t* req, uv_getnameinfo_cb getnameinfo_cb, const struct sockaddr* addr, int flags)
|
|
|
|
Asynchronous :man:`getnameinfo(3)`.
|
|
|
|
Returns 0 on success or an error code < 0 on failure. If successful, the
|
|
callback will get called sometime in the future with the lookup result.
|
|
Consult `man -s 3 getnameinfo` for more details.
|
|
|
|
.. versionchanged:: 1.3.0 the callback parameter is now allowed to be NULL,
|
|
in which case the request will run **synchronously**.
|
|
|
|
.. seealso:: The :c:type:`uv_req_t` API functions also apply.
|