← Back to branch summary

~webapps/unity-js-scopes/node.js

« back to all changes in this revision

Viewing changes to deps/uv/docs/src/udp.rst

  • Committer: Marcus Tomlinson
  • Date: 2015-11-13 07:59:04 UTC
  • Revision ID: marcus.tomlinson@canonical.com-20151113075904-h0swczmoq1rvstfc
Node v4 (stable)

Show diffs side-by-side

added added

removed removed

Lines of Context:
deps/uv/docs/src/udp.rst
 
1
 
 
2
.. _udp:
 
3
 
 
4
:c:type:`uv_udp_t` --- UDP handle
 
5
=================================
 
6
 
 
7
UDP handles encapsulate UDP communication for both clients and servers.
 
8
 
 
9
 
 
10
Data types
 
11
----------
 
12
 
 
13
.. c:type:: uv_udp_t
 
14
 
 
15
    UDP handle type.
 
16
 
 
17
.. c:type:: uv_udp_send_t
 
18
 
 
19
    UDP send request type.
 
20
 
 
21
.. c:type:: uv_udp_flags
 
22
 
 
23
    Flags used in :c:func:`uv_udp_bind` and :c:type:`uv_udp_recv_cb`..
 
24
 
 
25
    ::
 
26
 
 
27
        enum uv_udp_flags {
 
28
            /* Disables dual stack mode. */
 
29
            UV_UDP_IPV6ONLY = 1,
 
30
            /*
 
31
            * Indicates message was truncated because read buffer was too small. The
 
32
            * remainder was discarded by the OS. Used in uv_udp_recv_cb.
 
33
            */
 
34
            UV_UDP_PARTIAL = 2,
 
35
            /*
 
36
            * Indicates if SO_REUSEADDR will be set when binding the handle in
 
37
            * uv_udp_bind.
 
38
            * This sets the SO_REUSEPORT socket flag on the BSDs and OS X. On other
 
39
            * Unix platforms, it sets the SO_REUSEADDR flag. What that means is that
 
40
            * multiple threads or processes can bind to the same address without error
 
41
            * (provided they all set the flag) but only the last one to bind will receive
 
42
            * any traffic, in effect "stealing" the port from the previous listener.
 
43
            */
 
44
            UV_UDP_REUSEADDR = 4
 
45
        };
 
46
 
 
47
.. c:type:: void (*uv_udp_send_cb)(uv_udp_send_t* req, int status)
 
48
 
 
49
    Type definition for callback passed to :c:func:`uv_udp_send`, which is
 
50
    called after the data was sent.
 
51
 
 
52
.. c:type:: void (*uv_udp_recv_cb)(uv_udp_t* handle, ssize_t nread, const uv_buf_t* buf, const struct sockaddr* addr, unsigned flags)
 
53
 
 
54
    Type definition for callback passed to :c:func:`uv_udp_recv_start`, which
 
55
    is called when the endpoint receives data.
 
56
 
 
57
    * `handle`: UDP handle
 
58
    * `nread`:  Number of bytes that have been received.
 
59
      0 if there is no more data to read. You may discard or repurpose
 
60
      the read buffer. Note that 0 may also mean that an empty datagram
 
61
      was received (in this case `addr` is not NULL). < 0 if a transmission
 
62
      error was detected.
 
63
    * `buf`: :c:type:`uv_buf_t` with the received data.
 
64
    * `addr`: ``struct sockaddr*`` containing the address of the sender.
 
65
      Can be NULL. Valid for the duration of the callback only.
 
66
    * `flags`: One or more or'ed UV_UDP_* constants. Right now only
 
67
      ``UV_UDP_PARTIAL`` is used.
 
68
 
 
69
    .. note::
 
70
        The receive callback will be called with `nread` == 0 and `addr` == NULL when there is
 
71
        nothing to read, and with `nread` == 0 and `addr` != NULL when an empty UDP packet is
 
72
        received.
 
73
 
 
74
.. c:type:: uv_membership
 
75
 
 
76
    Membership type for a multicast address.
 
77
 
 
78
    ::
 
79
 
 
80
        typedef enum {
 
81
            UV_LEAVE_GROUP = 0,
 
82
            UV_JOIN_GROUP
 
83
        } uv_membership;
 
84
 
 
85
 
 
86
Public members
 
87
^^^^^^^^^^^^^^
 
88
 
 
89
.. c:member:: size_t uv_udp_t.send_queue_size
 
90
 
 
91
    Number of bytes queued for sending. This field strictly shows how much
 
92
    information is currently queued.
 
93
 
 
94
.. c:member:: size_t uv_udp_t.send_queue_count
 
95
 
 
96
    Number of send requests currently in the queue awaiting to be processed.
 
97
 
 
98
.. c:member:: uv_udp_t* uv_udp_send_t.handle
 
99
 
 
100
    UDP handle where this send request is taking place.
 
101
 
 
102
.. seealso:: The :c:type:`uv_handle_t` members also apply.
 
103
 
 
104
 
 
105
API
 
106
---
 
107
 
 
108
.. c:function:: int uv_udp_init(uv_loop_t* loop, uv_udp_t* handle)
 
109
 
 
110
    Initialize a new UDP handle. The actual socket is created lazily.
 
111
    Returns 0 on success.
 
112
 
 
113
.. c:function:: int uv_udp_init_ex(uv_loop_t* loop, uv_udp_t* handle, unsigned int flags)
 
114
 
 
115
    Initialize the handle with the specified flags. At the moment the lower 8 bits
 
116
    of the `flags` parameter are used as the socket domain. A socket will be created
 
117
    for the given domain. If the specified domain is ``AF_UNSPEC`` no socket is created,
 
118
    just like :c:func:`uv_udp_init`.
 
119
 
 
120
    .. versionadded:: 1.7.0
 
121
 
 
122
.. c:function:: int uv_udp_open(uv_udp_t* handle, uv_os_sock_t sock)
 
123
 
 
124
    Opens an existing file descriptor or Windows SOCKET as a UDP handle.
 
125
 
 
126
    Unix only:
 
127
    The only requirement of the `sock` argument is that it follows the datagram
 
128
    contract (works in unconnected mode, supports sendmsg()/recvmsg(), etc).
 
129
    In other words, other datagram-type sockets like raw sockets or netlink
 
130
    sockets can also be passed to this function.
 
131
 
 
132
    .. versionchanged:: 1.2.1 the file descriptor is set to non-blocking mode.
 
133
 
 
134
    .. note::
 
135
        The passed file descriptor or SOCKET is not checked for its type, but
 
136
        it's required that it represents a valid datagram socket.
 
137
 
 
138
.. c:function:: int uv_udp_bind(uv_udp_t* handle, const struct sockaddr* addr, unsigned int flags)
 
139
 
 
140
    Bind the UDP handle to an IP address and port.
 
141
 
 
142
    :param handle: UDP handle. Should have been initialized with
 
143
        :c:func:`uv_udp_init`.
 
144
 
 
145
    :param addr: `struct sockaddr_in` or `struct sockaddr_in6`
 
146
        with the address and port to bind to.
 
147
 
 
148
    :param flags: Indicate how the socket will be bound,
 
149
        ``UV_UDP_IPV6ONLY`` and ``UV_UDP_REUSEADDR`` are supported.
 
150
 
 
151
    :returns: 0 on success, or an error code < 0 on failure.
 
152
 
 
153
.. c:function:: int uv_udp_getsockname(const uv_udp_t* handle, struct sockaddr* name, int* namelen)
 
154
 
 
155
    Get the local IP and port of the UDP handle.
 
156
 
 
157
    :param handle: UDP handle. Should have been initialized with
 
158
        :c:func:`uv_udp_init` and bound.
 
159
 
 
160
    :param name: Pointer to the structure to be filled with the address data.
 
161
        In order to support IPv4 and IPv6 `struct sockaddr_storage` should be
 
162
        used.
 
163
 
 
164
    :param namelen: On input it indicates the data of the `name` field. On
 
165
        output it indicates how much of it was filled.
 
166
 
 
167
    :returns: 0 on success, or an error code < 0 on failure.
 
168
 
 
169
.. c:function:: int uv_udp_set_membership(uv_udp_t* handle, const char* multicast_addr, const char* interface_addr, uv_membership membership)
 
170
 
 
171
    Set membership for a multicast address
 
172
 
 
173
    :param handle: UDP handle. Should have been initialized with
 
174
        :c:func:`uv_udp_init`.
 
175
 
 
176
    :param multicast_addr: Multicast address to set membership for.
 
177
 
 
178
    :param interface_addr: Interface address.
 
179
 
 
180
    :param membership: Should be ``UV_JOIN_GROUP`` or ``UV_LEAVE_GROUP``.
 
181
 
 
182
    :returns: 0 on success, or an error code < 0 on failure.
 
183
 
 
184
.. c:function:: int uv_udp_set_multicast_loop(uv_udp_t* handle, int on)
 
185
 
 
186
    Set IP multicast loop flag. Makes multicast packets loop back to
 
187
    local sockets.
 
188
 
 
189
    :param handle: UDP handle. Should have been initialized with
 
190
        :c:func:`uv_udp_init`.
 
191
 
 
192
    :param on: 1 for on, 0 for off.
 
193
 
 
194
    :returns: 0 on success, or an error code < 0 on failure.
 
195
 
 
196
.. c:function:: int uv_udp_set_multicast_ttl(uv_udp_t* handle, int ttl)
 
197
 
 
198
    Set the multicast ttl.
 
199
 
 
200
    :param handle: UDP handle. Should have been initialized with
 
201
        :c:func:`uv_udp_init`.
 
202
 
 
203
    :param ttl: 1 through 255.
 
204
 
 
205
    :returns: 0 on success, or an error code < 0 on failure.
 
206
 
 
207
.. c:function:: int uv_udp_set_multicast_interface(uv_udp_t* handle, const char* interface_addr)
 
208
 
 
209
    Set the multicast interface to send or receive data on.
 
210
 
 
211
    :param handle: UDP handle. Should have been initialized with
 
212
        :c:func:`uv_udp_init`.
 
213
 
 
214
    :param interface_addr: interface address.
 
215
 
 
216
    :returns: 0 on success, or an error code < 0 on failure.
 
217
 
 
218
.. c:function:: int uv_udp_set_broadcast(uv_udp_t* handle, int on)
 
219
 
 
220
    Set broadcast on or off.
 
221
 
 
222
    :param handle: UDP handle. Should have been initialized with
 
223
        :c:func:`uv_udp_init`.
 
224
 
 
225
    :param on: 1 for on, 0 for off.
 
226
 
 
227
    :returns: 0 on success, or an error code < 0 on failure.
 
228
 
 
229
.. c:function:: int uv_udp_set_ttl(uv_udp_t* handle, int ttl)
 
230
 
 
231
    Set the time to live.
 
232
 
 
233
    :param handle: UDP handle. Should have been initialized with
 
234
        :c:func:`uv_udp_init`.
 
235
 
 
236
    :param ttl: 1 through 255.
 
237
 
 
238
    :returns: 0 on success, or an error code < 0 on failure.
 
239
 
 
240
.. c:function:: int uv_udp_send(uv_udp_send_t* req, uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr, uv_udp_send_cb send_cb)
 
241
 
 
242
    Send data over the UDP socket. If the socket has not previously been bound
 
243
    with :c:func:`uv_udp_bind` it will be bound to 0.0.0.0
 
244
    (the "all interfaces" IPv4 address) and a random port number.
 
245
 
 
246
    :param req: UDP request handle. Need not be initialized.
 
247
 
 
248
    :param handle: UDP handle. Should have been initialized with
 
249
        :c:func:`uv_udp_init`.
 
250
 
 
251
    :param bufs: List of buffers to send.
 
252
 
 
253
    :param nbufs: Number of buffers in `bufs`.
 
254
 
 
255
    :param addr: `struct sockaddr_in` or `struct sockaddr_in6` with the
 
256
        address and port of the remote peer.
 
257
 
 
258
    :param send_cb: Callback to invoke when the data has been sent out.
 
259
 
 
260
    :returns: 0 on success, or an error code < 0 on failure.
 
261
 
 
262
.. c:function:: int uv_udp_try_send(uv_udp_t* handle, const uv_buf_t bufs[], unsigned int nbufs, const struct sockaddr* addr)
 
263
 
 
264
    Same as :c:func:`uv_udp_send`, but won't queue a send request if it can't
 
265
    be completed immediately.
 
266
 
 
267
    :returns: >= 0: number of bytes sent (it matches the given buffer size).
 
268
        < 0: negative error code (``UV_EAGAIN`` is returned when the message
 
269
        can't be sent immediately).
 
270
 
 
271
.. c:function:: int uv_udp_recv_start(uv_udp_t* handle, uv_alloc_cb alloc_cb, uv_udp_recv_cb recv_cb)
 
272
 
 
273
    Prepare for receiving data. If the socket has not previously been bound
 
274
    with :c:func:`uv_udp_bind` it is bound to 0.0.0.0 (the "all interfaces"
 
275
    IPv4 address) and a random port number.
 
276
 
 
277
    :param handle: UDP handle. Should have been initialized with
 
278
        :c:func:`uv_udp_init`.
 
279
 
 
280
    :param alloc_cb: Callback to invoke when temporary storage is needed.
 
281
 
 
282
    :param recv_cb: Callback to invoke with received data.
 
283
 
 
284
    :returns: 0 on success, or an error code < 0 on failure.
 
285
 
 
286
.. c:function:: int uv_udp_recv_stop(uv_udp_t* handle)
 
287
 
 
288
    Stop listening for incoming datagrams.
 
289
 
 
290
    :param handle: UDP handle. Should have been initialized with
 
291
        :c:func:`uv_udp_init`.
 
292
 
 
293
    :returns: 0 on success, or an error code < 0 on failure.
 
294
 
 
295
.. seealso:: The :c:type:`uv_handle_t` API functions also apply.