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