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
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 on Sun Jul 7 2013 03:35:10 for Apache Portable Runtime by
1.8.1.2