1 | /* Licensed to the Apache Software Foundation (ASF) under one or more |
2 | * contributor license agreements. See the NOTICE file distributed with |
3 | * this work for additional information regarding copyright ownership. |
4 | * The ASF licenses this file to You under the Apache License, Version 2.0 |
5 | * (the "License"); you may not use this file except in compliance with |
6 | * the License. You may obtain a copy of the License at |
7 | * |
8 | * http://www.apache.org/licenses/LICENSE-2.0 |
9 | * |
10 | * Unless required by applicable law or agreed to in writing, software |
11 | * distributed under the License is distributed on an "AS IS" BASIS, |
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
13 | * See the License for the specific language governing permissions and |
14 | * limitations under the License. |
15 | */ |
16 | |
17 | #ifndef APR_NETWORK_IO_H |
18 | #define APR_NETWORK_IO_H |
19 | /** |
20 | * @file apr_network_io.h |
21 | * @brief APR Network library |
22 | */ |
23 | |
24 | #include "apr.h" |
25 | #include "apr_pools.h" |
26 | #include "apr_file_io.h" |
27 | #include "apr_errno.h" |
28 | #include "apr_inherit.h" |
29 | |
30 | #if APR_HAVE_NETINET_IN_H |
31 | #include <netinet/in.h> |
32 | #endif |
33 | |
34 | #ifdef __cplusplus |
35 | extern "C" { |
36 | #endif /* __cplusplus */ |
37 | |
38 | /** |
39 | * @defgroup apr_network_io Network Routines |
40 | * @ingroup APR |
41 | * @{ |
42 | */ |
43 | |
44 | #ifndef APR_MAX_SECS_TO_LINGER |
45 | /** Maximum seconds to linger */ |
46 | #define APR_MAX_SECS_TO_LINGER 30 |
47 | #endif |
48 | |
49 | #ifndef APRMAXHOSTLEN |
50 | /** Maximum hostname length */ |
51 | #define APRMAXHOSTLEN 256 |
52 | #endif |
53 | |
54 | #ifndef APR_ANYADDR |
55 | /** Default 'any' address */ |
56 | #define APR_ANYADDR "0.0.0.0" |
57 | #endif |
58 | |
59 | /** |
60 | * @defgroup apr_sockopt Socket option definitions |
61 | * @{ |
62 | */ |
63 | #define APR_SO_LINGER 1 /**< Linger */ |
64 | #define APR_SO_KEEPALIVE 2 /**< Keepalive */ |
65 | #define APR_SO_DEBUG 4 /**< Debug */ |
66 | #define APR_SO_NONBLOCK 8 /**< Non-blocking IO */ |
67 | #define APR_SO_REUSEADDR 16 /**< Reuse addresses */ |
68 | #define APR_SO_SNDBUF 64 /**< Send buffer */ |
69 | #define APR_SO_RCVBUF 128 /**< Receive buffer */ |
70 | #define APR_SO_DISCONNECTED 256 /**< Disconnected */ |
71 | #define APR_TCP_NODELAY 512 /**< For SCTP sockets, this is mapped |
72 | * to STCP_NODELAY internally. |
73 | */ |
74 | #define APR_TCP_NOPUSH 1024 /**< No push */ |
75 | #define APR_RESET_NODELAY 2048 /**< This flag is ONLY set internally |
76 | * when we set APR_TCP_NOPUSH with |
77 | * APR_TCP_NODELAY set to tell us that |
78 | * APR_TCP_NODELAY should be turned on |
79 | * again when NOPUSH is turned off |
80 | */ |
81 | #define APR_INCOMPLETE_READ 4096 /**< Set on non-blocking sockets |
82 | * (timeout != 0) on which the |
83 | * previous read() did not fill a buffer |
84 | * completely. the next apr_socket_recv() |
85 | * will first call select()/poll() rather than |
86 | * going straight into read(). (Can also |
87 | * be set by an application to force a |
88 | * select()/poll() call before the next |
89 | * read, in cases where the app expects |
90 | * that an immediate read would fail.) |
91 | */ |
92 | #define APR_INCOMPLETE_WRITE 8192 /**< like APR_INCOMPLETE_READ, but for write |
93 | * @see APR_INCOMPLETE_READ |
94 | */ |
95 | #define APR_IPV6_V6ONLY 16384 /**< Don't accept IPv4 connections on an |
96 | * IPv6 listening socket. |
97 | */ |
98 | #define APR_TCP_DEFER_ACCEPT 32768 /**< Delay accepting of new connections |
99 | * until data is available. |
100 | * @see apr_socket_accept_filter |
101 | */ |
102 | #define APR_SO_BROADCAST 65536 /**< Allow broadcast |
103 | */ |
104 | |
105 | /** @} */ |
106 | |
107 | /** Define what type of socket shutdown should occur. */ |
108 | typedef enum { |
109 | APR_SHUTDOWN_READ, /**< no longer allow read request */ |
110 | APR_SHUTDOWN_WRITE, /**< no longer allow write requests */ |
111 | APR_SHUTDOWN_READWRITE /**< no longer allow read or write requests */ |
112 | } apr_shutdown_how_e; |
113 | |
114 | #define APR_IPV4_ADDR_OK 0x01 /**< @see apr_sockaddr_info_get() */ |
115 | #define APR_IPV6_ADDR_OK 0x02 /**< @see apr_sockaddr_info_get() */ |
116 | |
117 | #if (!APR_HAVE_IN_ADDR) |
118 | /** |
119 | * We need to make sure we always have an in_addr type, so APR will just |
120 | * define it ourselves, if the platform doesn't provide it. |
121 | */ |
122 | struct in_addr { |
123 | apr_uint32_t s_addr; /**< storage to hold the IP# */ |
124 | }; |
125 | #endif |
126 | |
127 | /** @def APR_INADDR_NONE |
128 | * Not all platforms have a real INADDR_NONE. This macro replaces |
129 | * INADDR_NONE on all platforms. |
130 | */ |
131 | #ifdef INADDR_NONE |
132 | #define APR_INADDR_NONE INADDR_NONE |
133 | #else |
134 | #define APR_INADDR_NONE ((unsigned int) 0xffffffff) |
135 | #endif |
136 | |
137 | /** |
138 | * @def APR_INET |
139 | * Not all platforms have these defined, so we'll define them here |
140 | * The default values come from FreeBSD 4.1.1 |
141 | */ |
142 | #define APR_INET AF_INET |
143 | /** @def APR_UNSPEC |
144 | * Let the system decide which address family to use |
145 | */ |
146 | #ifdef AF_UNSPEC |
147 | #define APR_UNSPEC AF_UNSPEC |
148 | #else |
149 | #define APR_UNSPEC 0 |
150 | #endif |
151 | #if APR_HAVE_IPV6 |
152 | /** @def APR_INET6 |
153 | * IPv6 Address Family. Not all platforms may have this defined. |
154 | */ |
155 | |
156 | #define APR_INET6 AF_INET6 |
157 | #endif |
158 | |
159 | /** |
160 | * @defgroup IP_Proto IP Protocol Definitions for use when creating sockets |
161 | * @{ |
162 | */ |
163 | #define APR_PROTO_TCP 6 /**< TCP */ |
164 | #define APR_PROTO_UDP 17 /**< UDP */ |
165 | #define APR_PROTO_SCTP 132 /**< SCTP */ |
166 | /** @} */ |
167 | |
168 | /** |
169 | * Enum used to denote either the local and remote endpoint of a |
170 | * connection. |
171 | */ |
172 | typedef enum { |
173 | APR_LOCAL, /**< Socket information for local end of connection */ |
174 | APR_REMOTE /**< Socket information for remote end of connection */ |
175 | } apr_interface_e; |
176 | |
177 | /** |
178 | * The specific declaration of inet_addr's ... some platforms fall back |
179 | * inet_network (this is not good, but necessary) |
180 | */ |
181 | |
182 | #if APR_HAVE_INET_ADDR |
183 | #define apr_inet_addr inet_addr |
184 | #elif APR_HAVE_INET_NETWORK /* only DGUX, as far as I know */ |
185 | /** |
186 | * @warning |
187 | * not generally safe... inet_network() and inet_addr() perform |
188 | * different functions */ |
189 | #define apr_inet_addr inet_network |
190 | #endif |
191 | |
192 | /** A structure to represent sockets */ |
193 | typedef struct apr_socket_t apr_socket_t; |
194 | /** |
195 | * A structure to encapsulate headers and trailers for apr_socket_sendfile |
196 | */ |
197 | typedef struct apr_hdtr_t apr_hdtr_t; |
198 | /** A structure to represent in_addr */ |
199 | typedef struct in_addr apr_in_addr_t; |
200 | /** A structure to represent an IP subnet */ |
201 | typedef struct apr_ipsubnet_t apr_ipsubnet_t; |
202 | |
203 | /** @remark use apr_uint16_t just in case some system has a short that isn't 16 bits... */ |
204 | typedef apr_uint16_t apr_port_t; |
205 | |
206 | /** @remark It's defined here as I think it should all be platform safe... |
207 | * @see apr_sockaddr_t |
208 | */ |
209 | typedef struct apr_sockaddr_t apr_sockaddr_t; |
210 | /** |
211 | * APRs socket address type, used to ensure protocol independence |
212 | */ |
213 | struct apr_sockaddr_t { |
214 | /** The pool to use... */ |
215 | apr_pool_t *pool; |
216 | /** The hostname */ |
217 | char *hostname; |
218 | /** Either a string of the port number or the service name for the port */ |
219 | char *servname; |
220 | /** The numeric port */ |
221 | apr_port_t port; |
222 | /** The family */ |
223 | apr_int32_t family; |
224 | /** How big is the sockaddr we're using? */ |
225 | apr_socklen_t salen; |
226 | /** How big is the ip address structure we're using? */ |
227 | int ipaddr_len; |
228 | /** How big should the address buffer be? 16 for v4 or 46 for v6 |
229 | * used in inet_ntop... */ |
230 | int addr_str_len; |
231 | /** This points to the IP address structure within the appropriate |
232 | * sockaddr structure. */ |
233 | void *ipaddr_ptr; |
234 | /** If multiple addresses were found by apr_sockaddr_info_get(), this |
235 | * points to a representation of the next address. */ |
236 | apr_sockaddr_t *next; |
237 | /** Union of either IPv4 or IPv6 sockaddr. */ |
238 | union { |
239 | /** IPv4 sockaddr structure */ |
240 | struct sockaddr_in sin; |
241 | #if APR_HAVE_IPV6 |
242 | /** IPv6 sockaddr structure */ |
243 | struct sockaddr_in6 sin6; |
244 | #endif |
245 | #if APR_HAVE_SA_STORAGE |
246 | /** Placeholder to ensure that the size of this union is not |
247 | * dependent on whether APR_HAVE_IPV6 is defined. */ |
248 | struct sockaddr_storage sas; |
249 | #endif |
250 | } sa; |
251 | }; |
252 | |
253 | #if APR_HAS_SENDFILE |
254 | /** |
255 | * Support reusing the socket on platforms which support it (from disconnect, |
256 | * specifically Win32. |
257 | * @remark Optional flag passed into apr_socket_sendfile() |
258 | */ |
259 | #define APR_SENDFILE_DISCONNECT_SOCKET 1 |
260 | #endif |
261 | |
262 | /** A structure to encapsulate headers and trailers for apr_socket_sendfile */ |
263 | struct apr_hdtr_t { |
264 | /** An iovec to store the headers sent before the file. */ |
265 | struct iovec* ; |
266 | /** number of headers in the iovec */ |
267 | int ; |
268 | /** An iovec to store the trailers sent after the file. */ |
269 | struct iovec* trailers; |
270 | /** number of trailers in the iovec */ |
271 | int numtrailers; |
272 | }; |
273 | |
274 | /* function definitions */ |
275 | |
276 | /** |
277 | * Create a socket. |
278 | * @param new_sock The new socket that has been set up. |
279 | * @param family The address family of the socket (e.g., APR_INET). |
280 | * @param type The type of the socket (e.g., SOCK_STREAM). |
281 | * @param protocol The protocol of the socket (e.g., APR_PROTO_TCP). |
282 | * @param cont The pool for the apr_socket_t and associated storage. |
283 | * @note The pool will be used by various functions that operate on the |
284 | * socket. The caller must ensure that it is not used by other threads |
285 | * at the same time. |
286 | */ |
287 | APR_DECLARE(apr_status_t) apr_socket_create(apr_socket_t **new_sock, |
288 | int family, int type, |
289 | int protocol, |
290 | apr_pool_t *cont); |
291 | |
292 | /** |
293 | * Shutdown either reading, writing, or both sides of a socket. |
294 | * @param thesocket The socket to close |
295 | * @param how How to shutdown the socket. One of: |
296 | * <PRE> |
297 | * APR_SHUTDOWN_READ no longer allow read requests |
298 | * APR_SHUTDOWN_WRITE no longer allow write requests |
299 | * APR_SHUTDOWN_READWRITE no longer allow read or write requests |
300 | * </PRE> |
301 | * @see apr_shutdown_how_e |
302 | * @remark This does not actually close the socket descriptor, it just |
303 | * controls which calls are still valid on the socket. |
304 | */ |
305 | APR_DECLARE(apr_status_t) apr_socket_shutdown(apr_socket_t *thesocket, |
306 | apr_shutdown_how_e how); |
307 | |
308 | /** |
309 | * Close a socket. |
310 | * @param thesocket The socket to close |
311 | */ |
312 | APR_DECLARE(apr_status_t) apr_socket_close(apr_socket_t *thesocket); |
313 | |
314 | /** |
315 | * Bind the socket to its associated port |
316 | * @param sock The socket to bind |
317 | * @param sa The socket address to bind to |
318 | * @remark This may be where we will find out if there is any other process |
319 | * using the selected port. |
320 | */ |
321 | APR_DECLARE(apr_status_t) apr_socket_bind(apr_socket_t *sock, |
322 | apr_sockaddr_t *sa); |
323 | |
324 | /** |
325 | * Listen to a bound socket for connections. |
326 | * @param sock The socket to listen on |
327 | * @param backlog The number of outstanding connections allowed in the sockets |
328 | * listen queue. If this value is less than zero, the listen |
329 | * queue size is set to zero. |
330 | */ |
331 | APR_DECLARE(apr_status_t) apr_socket_listen(apr_socket_t *sock, |
332 | apr_int32_t backlog); |
333 | |
334 | /** |
335 | * Accept a new connection request |
336 | * @param new_sock A copy of the socket that is connected to the socket that |
337 | * made the connection request. This is the socket which should |
338 | * be used for all future communication. |
339 | * @param sock The socket we are listening on. |
340 | * @param connection_pool The pool for the new socket. |
341 | * @note The pool will be used by various functions that operate on the |
342 | * socket. The caller must ensure that it is not used by other threads |
343 | * at the same time. |
344 | */ |
345 | APR_DECLARE(apr_status_t) apr_socket_accept(apr_socket_t **new_sock, |
346 | apr_socket_t *sock, |
347 | apr_pool_t *connection_pool); |
348 | |
349 | /** |
350 | * Issue a connection request to a socket either on the same machine |
351 | * or a different one. |
352 | * @param sock The socket we wish to use for our side of the connection |
353 | * @param sa The address of the machine we wish to connect to. |
354 | */ |
355 | APR_DECLARE(apr_status_t) apr_socket_connect(apr_socket_t *sock, |
356 | apr_sockaddr_t *sa); |
357 | |
358 | /** |
359 | * Determine whether the receive part of the socket has been closed by |
360 | * the peer (such that a subsequent call to apr_socket_read would |
361 | * return APR_EOF), if the socket's receive buffer is empty. This |
362 | * function does not block waiting for I/O. |
363 | * |
364 | * @param sock The socket to check |
365 | * @param atreadeof If APR_SUCCESS is returned, *atreadeof is set to |
366 | * non-zero if a subsequent read would return APR_EOF |
367 | * @return an error is returned if it was not possible to determine the |
368 | * status, in which case *atreadeof is not changed. |
369 | */ |
370 | APR_DECLARE(apr_status_t) apr_socket_atreadeof(apr_socket_t *sock, |
371 | int *atreadeof); |
372 | |
373 | /** |
374 | * Create apr_sockaddr_t from hostname, address family, and port. |
375 | * @param sa The new apr_sockaddr_t. |
376 | * @param hostname The hostname or numeric address string to resolve/parse, or |
377 | * NULL to build an address that corresponds to 0.0.0.0 or :: |
378 | * @param family The address family to use, or APR_UNSPEC if the system should |
379 | * decide. |
380 | * @param port The port number. |
381 | * @param flags Special processing flags: |
382 | * <PRE> |
383 | * APR_IPV4_ADDR_OK first query for IPv4 addresses; only look |
384 | * for IPv6 addresses if the first query failed; |
385 | * only valid if family is APR_UNSPEC and hostname |
386 | * isn't NULL; mutually exclusive with |
387 | * APR_IPV6_ADDR_OK |
388 | * APR_IPV6_ADDR_OK first query for IPv6 addresses; only look |
389 | * for IPv4 addresses if the first query failed; |
390 | * only valid if family is APR_UNSPEC and hostname |
391 | * isn't NULL and APR_HAVE_IPV6; mutually exclusive |
392 | * with APR_IPV4_ADDR_OK |
393 | * </PRE> |
394 | * @param p The pool for the apr_sockaddr_t and associated storage. |
395 | */ |
396 | APR_DECLARE(apr_status_t) apr_sockaddr_info_get(apr_sockaddr_t **sa, |
397 | const char *hostname, |
398 | apr_int32_t family, |
399 | apr_port_t port, |
400 | apr_int32_t flags, |
401 | apr_pool_t *p); |
402 | |
403 | /** |
404 | * Look up the host name from an apr_sockaddr_t. |
405 | * @param hostname The hostname. |
406 | * @param sa The apr_sockaddr_t. |
407 | * @param flags Special processing flags. |
408 | * @remark Results can vary significantly between platforms |
409 | * when processing wildcard socket addresses. |
410 | */ |
411 | APR_DECLARE(apr_status_t) apr_getnameinfo(char **hostname, |
412 | apr_sockaddr_t *sa, |
413 | apr_int32_t flags); |
414 | |
415 | /** |
416 | * Parse hostname/IP address with scope id and port. |
417 | * |
418 | * Any of the following strings are accepted: |
419 | * 8080 (just the port number) |
420 | * www.apache.org (just the hostname) |
421 | * www.apache.org:8080 (hostname and port number) |
422 | * [fe80::1]:80 (IPv6 numeric address string only) |
423 | * [fe80::1%eth0] (IPv6 numeric address string and scope id) |
424 | * |
425 | * Invalid strings: |
426 | * (empty string) |
427 | * [abc] (not valid IPv6 numeric address string) |
428 | * abc:65536 (invalid port number) |
429 | * |
430 | * @param addr The new buffer containing just the hostname. On output, *addr |
431 | * will be NULL if no hostname/IP address was specfied. |
432 | * @param scope_id The new buffer containing just the scope id. On output, |
433 | * *scope_id will be NULL if no scope id was specified. |
434 | * @param port The port number. On output, *port will be 0 if no port was |
435 | * specified. |
436 | * ### FIXME: 0 is a legal port (per RFC 1700). this should |
437 | * ### return something besides zero if the port is missing. |
438 | * @param str The input string to be parsed. |
439 | * @param p The pool from which *addr and *scope_id are allocated. |
440 | * @remark If scope id shouldn't be allowed, check for scope_id != NULL in |
441 | * addition to checking the return code. If addr/hostname should be |
442 | * required, check for addr == NULL in addition to checking the |
443 | * return code. |
444 | */ |
445 | APR_DECLARE(apr_status_t) apr_parse_addr_port(char **addr, |
446 | char **scope_id, |
447 | apr_port_t *port, |
448 | const char *str, |
449 | apr_pool_t *p); |
450 | |
451 | /** |
452 | * Get name of the current machine |
453 | * @param buf A buffer to store the hostname in. |
454 | * @param len The maximum length of the hostname that can be stored in the |
455 | * buffer provided. The suggested length is APRMAXHOSTLEN + 1. |
456 | * @param cont The pool to use. |
457 | * @remark If the buffer was not large enough, an error will be returned. |
458 | */ |
459 | APR_DECLARE(apr_status_t) apr_gethostname(char *buf, int len, apr_pool_t *cont); |
460 | |
461 | /** |
462 | * Return the data associated with the current socket |
463 | * @param data The user data associated with the socket. |
464 | * @param key The key to associate with the user data. |
465 | * @param sock The currently open socket. |
466 | */ |
467 | APR_DECLARE(apr_status_t) apr_socket_data_get(void **data, const char *key, |
468 | apr_socket_t *sock); |
469 | |
470 | /** |
471 | * Set the data associated with the current socket. |
472 | * @param sock The currently open socket. |
473 | * @param data The user data to associate with the socket. |
474 | * @param key The key to associate with the data. |
475 | * @param cleanup The cleanup to call when the socket is destroyed. |
476 | */ |
477 | APR_DECLARE(apr_status_t) apr_socket_data_set(apr_socket_t *sock, void *data, |
478 | const char *key, |
479 | apr_status_t (*cleanup)(void*)); |
480 | |
481 | /** |
482 | * Send data over a network. |
483 | * @param sock The socket to send the data over. |
484 | * @param buf The buffer which contains the data to be sent. |
485 | * @param len On entry, the number of bytes to send; on exit, the number |
486 | * of bytes sent. |
487 | * @remark |
488 | * <PRE> |
489 | * This functions acts like a blocking write by default. To change |
490 | * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK |
491 | * socket option. |
492 | * |
493 | * It is possible for both bytes to be sent and an error to be returned. |
494 | * |
495 | * APR_EINTR is never returned. |
496 | * </PRE> |
497 | */ |
498 | APR_DECLARE(apr_status_t) apr_socket_send(apr_socket_t *sock, const char *buf, |
499 | apr_size_t *len); |
500 | |
501 | /** |
502 | * Send multiple buffers over a network. |
503 | * @param sock The socket to send the data over. |
504 | * @param vec The array of iovec structs containing the data to send |
505 | * @param nvec The number of iovec structs in the array |
506 | * @param len Receives the number of bytes actually written |
507 | * @remark |
508 | * <PRE> |
509 | * This functions acts like a blocking write by default. To change |
510 | * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK |
511 | * socket option. |
512 | * The number of bytes actually sent is stored in argument 4. |
513 | * |
514 | * It is possible for both bytes to be sent and an error to be returned. |
515 | * |
516 | * APR_EINTR is never returned. |
517 | * </PRE> |
518 | */ |
519 | APR_DECLARE(apr_status_t) apr_socket_sendv(apr_socket_t *sock, |
520 | const struct iovec *vec, |
521 | apr_int32_t nvec, apr_size_t *len); |
522 | |
523 | /** |
524 | * @param sock The socket to send from |
525 | * @param where The apr_sockaddr_t describing where to send the data |
526 | * @param flags The flags to use |
527 | * @param buf The data to send |
528 | * @param len The length of the data to send |
529 | */ |
530 | APR_DECLARE(apr_status_t) apr_socket_sendto(apr_socket_t *sock, |
531 | apr_sockaddr_t *where, |
532 | apr_int32_t flags, const char *buf, |
533 | apr_size_t *len); |
534 | |
535 | /** |
536 | * Read data from a socket. On success, the address of the peer from |
537 | * which the data was sent is copied into the @a from parameter, and the |
538 | * @a len parameter is updated to give the number of bytes written to |
539 | * @a buf. |
540 | * |
541 | * @param from Updated with the address from which the data was received |
542 | * @param sock The socket to use |
543 | * @param flags The flags to use |
544 | * @param buf The buffer to use |
545 | * @param len The length of the available buffer |
546 | */ |
547 | |
548 | APR_DECLARE(apr_status_t) apr_socket_recvfrom(apr_sockaddr_t *from, |
549 | apr_socket_t *sock, |
550 | apr_int32_t flags, char *buf, |
551 | apr_size_t *len); |
552 | |
553 | #if APR_HAS_SENDFILE || defined(DOXYGEN) |
554 | |
555 | /** |
556 | * Send a file from an open file descriptor to a socket, along with |
557 | * optional headers and trailers |
558 | * @param sock The socket to which we're writing |
559 | * @param file The open file from which to read |
560 | * @param hdtr A structure containing the headers and trailers to send |
561 | * @param offset Offset into the file where we should begin writing |
562 | * @param len (input) - Number of bytes to send from the file |
563 | * (output) - Number of bytes actually sent, |
564 | * including headers, file, and trailers |
565 | * @param flags APR flags that are mapped to OS specific flags |
566 | * @remark This functions acts like a blocking write by default. To change |
567 | * this behavior, use apr_socket_timeout_set() or the |
568 | * APR_SO_NONBLOCK socket option. |
569 | * The number of bytes actually sent is stored in the len parameter. |
570 | * The offset parameter is passed by reference for no reason; its |
571 | * value will never be modified by the apr_socket_sendfile() function. |
572 | */ |
573 | APR_DECLARE(apr_status_t) apr_socket_sendfile(apr_socket_t *sock, |
574 | apr_file_t *file, |
575 | apr_hdtr_t *hdtr, |
576 | apr_off_t *offset, |
577 | apr_size_t *len, |
578 | apr_int32_t flags); |
579 | |
580 | #endif /* APR_HAS_SENDFILE */ |
581 | |
582 | /** |
583 | * Read data from a network. |
584 | * @param sock The socket to read the data from. |
585 | * @param buf The buffer to store the data in. |
586 | * @param len On entry, the number of bytes to receive; on exit, the number |
587 | * of bytes received. |
588 | * @remark |
589 | * <PRE> |
590 | * This functions acts like a blocking read by default. To change |
591 | * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK |
592 | * socket option. |
593 | * The number of bytes actually received is stored in argument 3. |
594 | * |
595 | * It is possible for both bytes to be received and an APR_EOF or |
596 | * other error to be returned. |
597 | * |
598 | * APR_EINTR is never returned. |
599 | * </PRE> |
600 | */ |
601 | APR_DECLARE(apr_status_t) apr_socket_recv(apr_socket_t *sock, |
602 | char *buf, apr_size_t *len); |
603 | |
604 | /** |
605 | * Setup socket options for the specified socket |
606 | * @param sock The socket to set up. |
607 | * @param opt The option we would like to configure. One of: |
608 | * <PRE> |
609 | * APR_SO_DEBUG -- turn on debugging information |
610 | * APR_SO_KEEPALIVE -- keep connections active |
611 | * APR_SO_LINGER -- lingers on close if data is present |
612 | * APR_SO_NONBLOCK -- Turns blocking on/off for socket |
613 | * When this option is enabled, use |
614 | * the APR_STATUS_IS_EAGAIN() macro to |
615 | * see if a send or receive function |
616 | * could not transfer data without |
617 | * blocking. |
618 | * APR_SO_REUSEADDR -- The rules used in validating addresses |
619 | * supplied to bind should allow reuse |
620 | * of local addresses. |
621 | * APR_SO_SNDBUF -- Set the SendBufferSize |
622 | * APR_SO_RCVBUF -- Set the ReceiveBufferSize |
623 | * </PRE> |
624 | * @param on Value for the option. |
625 | */ |
626 | APR_DECLARE(apr_status_t) apr_socket_opt_set(apr_socket_t *sock, |
627 | apr_int32_t opt, apr_int32_t on); |
628 | |
629 | /** |
630 | * Setup socket timeout for the specified socket |
631 | * @param sock The socket to set up. |
632 | * @param t Value for the timeout. |
633 | * <PRE> |
634 | * t > 0 -- read and write calls return APR_TIMEUP if specified time |
635 | * elapsess with no data read or written |
636 | * t == 0 -- read and write calls never block |
637 | * t < 0 -- read and write calls block |
638 | * </PRE> |
639 | */ |
640 | APR_DECLARE(apr_status_t) apr_socket_timeout_set(apr_socket_t *sock, |
641 | apr_interval_time_t t); |
642 | |
643 | /** |
644 | * Query socket options for the specified socket |
645 | * @param sock The socket to query |
646 | * @param opt The option we would like to query. One of: |
647 | * <PRE> |
648 | * APR_SO_DEBUG -- turn on debugging information |
649 | * APR_SO_KEEPALIVE -- keep connections active |
650 | * APR_SO_LINGER -- lingers on close if data is present |
651 | * APR_SO_NONBLOCK -- Turns blocking on/off for socket |
652 | * APR_SO_REUSEADDR -- The rules used in validating addresses |
653 | * supplied to bind should allow reuse |
654 | * of local addresses. |
655 | * APR_SO_SNDBUF -- Set the SendBufferSize |
656 | * APR_SO_RCVBUF -- Set the ReceiveBufferSize |
657 | * APR_SO_DISCONNECTED -- Query the disconnected state of the socket. |
658 | * (Currently only used on Windows) |
659 | * </PRE> |
660 | * @param on Socket option returned on the call. |
661 | */ |
662 | APR_DECLARE(apr_status_t) apr_socket_opt_get(apr_socket_t *sock, |
663 | apr_int32_t opt, apr_int32_t *on); |
664 | |
665 | /** |
666 | * Query socket timeout for the specified socket |
667 | * @param sock The socket to query |
668 | * @param t Socket timeout returned from the query. |
669 | */ |
670 | APR_DECLARE(apr_status_t) apr_socket_timeout_get(apr_socket_t *sock, |
671 | apr_interval_time_t *t); |
672 | |
673 | /** |
674 | * Query the specified socket if at the OOB/Urgent data mark |
675 | * @param sock The socket to query |
676 | * @param atmark Is set to true if socket is at the OOB/urgent mark, |
677 | * otherwise is set to false. |
678 | */ |
679 | APR_DECLARE(apr_status_t) apr_socket_atmark(apr_socket_t *sock, |
680 | int *atmark); |
681 | |
682 | /** |
683 | * Return an address associated with a socket; either the address to |
684 | * which the socket is bound locally or the address of the peer |
685 | * to which the socket is connected. |
686 | * @param sa The returned apr_sockaddr_t. |
687 | * @param which Whether to retrieve the local or remote address |
688 | * @param sock The socket to use |
689 | */ |
690 | APR_DECLARE(apr_status_t) apr_socket_addr_get(apr_sockaddr_t **sa, |
691 | apr_interface_e which, |
692 | apr_socket_t *sock); |
693 | |
694 | /** |
695 | * Return the IP address (in numeric address string format) in |
696 | * an APR socket address. APR will allocate storage for the IP address |
697 | * string from the pool of the apr_sockaddr_t. |
698 | * @param addr The IP address. |
699 | * @param sockaddr The socket address to reference. |
700 | */ |
701 | APR_DECLARE(apr_status_t) apr_sockaddr_ip_get(char **addr, |
702 | apr_sockaddr_t *sockaddr); |
703 | |
704 | /** |
705 | * Write the IP address (in numeric address string format) of the APR |
706 | * socket address @a sockaddr into the buffer @a buf (of size @a buflen). |
707 | * @param sockaddr The socket address to reference. |
708 | */ |
709 | APR_DECLARE(apr_status_t) apr_sockaddr_ip_getbuf(char *buf, apr_size_t buflen, |
710 | apr_sockaddr_t *sockaddr); |
711 | |
712 | /** |
713 | * See if the IP addresses in two APR socket addresses are |
714 | * equivalent. Appropriate logic is present for comparing |
715 | * IPv4-mapped IPv6 addresses with IPv4 addresses. |
716 | * |
717 | * @param addr1 One of the APR socket addresses. |
718 | * @param addr2 The other APR socket address. |
719 | * @remark The return value will be non-zero if the addresses |
720 | * are equivalent. |
721 | */ |
722 | APR_DECLARE(int) apr_sockaddr_equal(const apr_sockaddr_t *addr1, |
723 | const apr_sockaddr_t *addr2); |
724 | |
725 | /** |
726 | * See if the IP address in an APR socket address refers to the wildcard |
727 | * address for the protocol family (e.g., INADDR_ANY for IPv4). |
728 | * |
729 | * @param addr The APR socket address to examine. |
730 | * @remark The return value will be non-zero if the address is |
731 | * initialized and is the wildcard address. |
732 | */ |
733 | APR_DECLARE(int) apr_sockaddr_is_wildcard(const apr_sockaddr_t *addr); |
734 | |
735 | /** |
736 | * Return the type of the socket. |
737 | * @param sock The socket to query. |
738 | * @param type The returned type (e.g., SOCK_STREAM). |
739 | */ |
740 | APR_DECLARE(apr_status_t) apr_socket_type_get(apr_socket_t *sock, |
741 | int *type); |
742 | |
743 | /** |
744 | * Given an apr_sockaddr_t and a service name, set the port for the service |
745 | * @param sockaddr The apr_sockaddr_t that will have its port set |
746 | * @param servname The name of the service you wish to use |
747 | */ |
748 | APR_DECLARE(apr_status_t) apr_getservbyname(apr_sockaddr_t *sockaddr, |
749 | const char *servname); |
750 | /** |
751 | * Build an ip-subnet representation from an IP address and optional netmask or |
752 | * number-of-bits. |
753 | * @param ipsub The new ip-subnet representation |
754 | * @param ipstr The input IP address string |
755 | * @param mask_or_numbits The input netmask or number-of-bits string, or NULL |
756 | * @param p The pool to allocate from |
757 | */ |
758 | APR_DECLARE(apr_status_t) apr_ipsubnet_create(apr_ipsubnet_t **ipsub, |
759 | const char *ipstr, |
760 | const char *mask_or_numbits, |
761 | apr_pool_t *p); |
762 | |
763 | /** |
764 | * Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet |
765 | * representation. |
766 | * @param ipsub The ip-subnet representation |
767 | * @param sa The socket address to test |
768 | * @return non-zero if the socket address is within the subnet, 0 otherwise |
769 | */ |
770 | APR_DECLARE(int) apr_ipsubnet_test(apr_ipsubnet_t *ipsub, apr_sockaddr_t *sa); |
771 | |
772 | #if APR_HAS_SO_ACCEPTFILTER || defined(DOXYGEN) |
773 | /** |
774 | * Set an OS level accept filter. |
775 | * @param sock The socket to put the accept filter on. |
776 | * @param name The accept filter |
777 | * @param args Any extra args to the accept filter. Passing NULL here removes |
778 | * the accept filter. |
779 | * @bug name and args should have been declared as const char *, as they are in |
780 | * APR 2.0 |
781 | */ |
782 | apr_status_t apr_socket_accept_filter(apr_socket_t *sock, char *name, |
783 | char *args); |
784 | #endif |
785 | |
786 | /** |
787 | * Return the protocol of the socket. |
788 | * @param sock The socket to query. |
789 | * @param protocol The returned protocol (e.g., APR_PROTO_TCP). |
790 | */ |
791 | APR_DECLARE(apr_status_t) apr_socket_protocol_get(apr_socket_t *sock, |
792 | int *protocol); |
793 | |
794 | /** |
795 | * Get the pool used by the socket. |
796 | */ |
797 | APR_POOL_DECLARE_ACCESSOR(socket); |
798 | |
799 | /** |
800 | * Set a socket to be inherited by child processes. |
801 | */ |
802 | APR_DECLARE_INHERIT_SET(socket); |
803 | |
804 | /** |
805 | * Unset a socket from being inherited by child processes. |
806 | */ |
807 | APR_DECLARE_INHERIT_UNSET(socket); |
808 | |
809 | /** |
810 | * @defgroup apr_mcast IP Multicast |
811 | * @{ |
812 | */ |
813 | |
814 | /** |
815 | * Join a Multicast Group |
816 | * @param sock The socket to join a multicast group |
817 | * @param join The address of the multicast group to join |
818 | * @param iface Address of the interface to use. If NULL is passed, the |
819 | * default multicast interface will be used. (OS Dependent) |
820 | * @param source Source Address to accept transmissions from (non-NULL |
821 | * implies Source-Specific Multicast) |
822 | */ |
823 | APR_DECLARE(apr_status_t) apr_mcast_join(apr_socket_t *sock, |
824 | apr_sockaddr_t *join, |
825 | apr_sockaddr_t *iface, |
826 | apr_sockaddr_t *source); |
827 | |
828 | /** |
829 | * Leave a Multicast Group. All arguments must be the same as |
830 | * apr_mcast_join. |
831 | * @param sock The socket to leave a multicast group |
832 | * @param addr The address of the multicast group to leave |
833 | * @param iface Address of the interface to use. If NULL is passed, the |
834 | * default multicast interface will be used. (OS Dependent) |
835 | * @param source Source Address to accept transmissions from (non-NULL |
836 | * implies Source-Specific Multicast) |
837 | */ |
838 | APR_DECLARE(apr_status_t) apr_mcast_leave(apr_socket_t *sock, |
839 | apr_sockaddr_t *addr, |
840 | apr_sockaddr_t *iface, |
841 | apr_sockaddr_t *source); |
842 | |
843 | /** |
844 | * Set the Multicast Time to Live (ttl) for a multicast transmission. |
845 | * @param sock The socket to set the multicast ttl |
846 | * @param ttl Time to live to Assign. 0-255, default=1 |
847 | * @remark If the TTL is 0, packets will only be seen by sockets on |
848 | * the local machine, and only when multicast loopback is enabled. |
849 | */ |
850 | APR_DECLARE(apr_status_t) apr_mcast_hops(apr_socket_t *sock, |
851 | apr_byte_t ttl); |
852 | |
853 | /** |
854 | * Toggle IP Multicast Loopback |
855 | * @param sock The socket to set multicast loopback |
856 | * @param opt 0=disable, 1=enable |
857 | */ |
858 | APR_DECLARE(apr_status_t) apr_mcast_loopback(apr_socket_t *sock, |
859 | apr_byte_t opt); |
860 | |
861 | |
862 | /** |
863 | * Set the Interface to be used for outgoing Multicast Transmissions. |
864 | * @param sock The socket to set the multicast interface on |
865 | * @param iface Address of the interface to use for Multicast |
866 | */ |
867 | APR_DECLARE(apr_status_t) apr_mcast_interface(apr_socket_t *sock, |
868 | apr_sockaddr_t *iface); |
869 | |
870 | /** @} */ |
871 | |
872 | /** @} */ |
873 | |
874 | #ifdef __cplusplus |
875 | } |
876 | #endif |
877 | |
878 | #endif /* ! APR_NETWORK_IO_H */ |
879 | |
880 | |