Apache Portable Runtime
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
include
apr_network_io.h
Go to the documentation of this file.
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*
headers
;
266
/** number of headers in the iovec */
267
int
numheaders
;
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
Generated on Thu Sep 30 2021 21:18:41 for Apache Portable Runtime by
1.8.1.2