Connection Library

Collaboration diagram for Connection Library:

Macros
#define	AP_BUCKET_IS_EOC(e)   (e->type == &ap_bucket_type_eoc)

Functions
void	ap_process_connection (conn_rec *c, void *csd)
apr_status_t	ap_shutdown_conn (conn_rec *c, int flush)
void	ap_flush_conn (conn_rec *c)
void	ap_lingering_close (conn_rec *c)
int	ap_prep_lingering_close (conn_rec *c)
int	ap_start_lingering_close (conn_rec *c)
conn_rec *	create_connection (apr_pool_t *p, server_rec *server, apr_socket_t *csd, long conn_id, void *sbh, apr_bucket_alloc_t *alloc)
int	pre_connection (conn_rec *c, void *csd)
int	process_connection (conn_rec *c)
int	pre_close_connection (conn_rec *c)
int	ap_pre_connection (conn_rec *c, void *csd)
conn_rec *	create_secondary_connection (apr_pool_t *p, conn_rec *master, apr_bucket_alloc_t *alloc)
conn_rec *	ap_create_connection (apr_pool_t *p, server_rec *server, apr_socket_t *csd, long conn_id, void *sbh, apr_bucket_alloc_t *alloc, unsigned int outgoing)
conn_rec *	ap_create_secondary_connection (apr_pool_t *pool, conn_rec *master, apr_bucket_alloc_t *alloc)
apr_bucket *	ap_bucket_eoc_make (apr_bucket *b)
apr_bucket *	ap_bucket_eoc_create (apr_bucket_alloc_t *list)

Variables
AP_DECLARE_DATA const apr_bucket_type_t	ap_bucket_type_eoc

Detailed Description

Macro Definition Documentation

AP_BUCKET_IS_EOC

#define AP_BUCKET_IS_EOC

(

e

)

(e->type == &ap_bucket_type_eoc)

Determine if a bucket is an End Of Connection (EOC) bucket

Parameters

e	The bucket to inspect

Returns

true or false

Function Documentation

ap_bucket_eoc_create()

apr_bucket* ap_bucket_eoc_create

(

apr_bucket_alloc_t *

list

)

Create a bucket referring to an End Of Connection (EOC). This indicates that the connection will be closed.

Parameters

list	The freelist from which this bucket should be allocated

Returns

The new bucket, or NULL if allocation failed

ap_bucket_eoc_make()

apr_bucket* ap_bucket_eoc_make

(

apr_bucket *

b

)

Make the bucket passed in an End Of Connection (EOC) bucket

Parameters

b	The bucket to make into an EOC bucket

Returns

The new bucket, or NULL if allocation failed

ap_create_connection()

conn_rec* ap_create_connection	(	apr_pool_t *	p,
		server_rec *	server,
		apr_socket_t *	csd,
		long	conn_id,
		void *	sbh,
		apr_bucket_alloc_t *	alloc,
		unsigned int	outgoing
	)

Create a new server/incoming or client/outgoing/proxy connection

Parameters

p	The pool from which to allocate the connection record
server	The server record to create the connection too.
csd	The socket that has been accepted
conn_id	A unique identifier for this connection. The ID only needs to be unique at that time, not forever.
sbh	A handle to scoreboard information for this connection.
alloc	The bucket allocator to use for all bucket/brigade creations
outgoing	Whether it's an outgoing (client) connection

Returns

An allocated connection record or NULL.

Remarks

To allow for future flags, outgoing must be a boolean (0 or 1) for now, otherwise NULL is returned

ap_create_secondary_connection()

conn_rec* ap_create_secondary_connection	(	apr_pool_t *	pool,
		conn_rec *	master,
		apr_bucket_alloc_t *	alloc
	)

Create a new secondary connection based on a master one.

Parameters

pool	The pool for the secondary connection
master	The master connection this belongs to.
alloc	The bucket allocator to use for all bucket/brigade creations

Returns

An allocated connection record or NULL.

ap_flush_conn()

void ap_flush_conn

(

conn_rec *

c

)

Flushes all remain data in the client send buffer

Parameters

c	The connection to flush

Remarks

calls ap_shutdown_conn(c, 1)

ap_lingering_close()

void ap_lingering_close

(

conn_rec *

c

)

This function is responsible for the following cases:

we now proceed to read from the client until we get EOF, or until
MAX_SECS_TO_LINGER has passed.  The reasons for doing this are
documented in a draft:

http://tools.ietf.org/html/draft-ietf-http-connection-00.txt

in a nutshell -- if we don't make this effort we risk causing
TCP RST packets to be sent which can tear down a connection before
all the response data has been sent to the client.

Parameters

c	The connection we are closing

ap_pre_connection()

int ap_pre_connection	(	conn_rec *	c,
		void *	csd
	)

This is a wrapper around ap_run_pre_connection. In case that ap_run_pre_connection returns an error it marks the connection as aborted and ensures that the basic connection setup normally done by the core module is done in case it was not done so far.

Parameters

c	The connection on which the request has been received. Same as for the pre_connection hook.
csd	The mechanism on which this connection is to be read. Most times this will be a socket, but it is up to the module that accepts the request to determine the exact type. Same as for the pre_connection hook.

Returns

The result of ap_run_pre_connection

ap_prep_lingering_close()

int ap_prep_lingering_close

(

conn_rec *

c

)

ap_process_connection()

void ap_process_connection	(	conn_rec *	c,
		void *	csd
	)

This is the protocol module driver. This calls all of the pre-connection and connection hooks for all protocol modules.

Parameters

c	The connection on which the request is read
csd	The mechanism on which this connection is to be read. Most times this will be a socket, but it is up to the module that accepts the request to determine the exact type.

ap_shutdown_conn()

apr_status_t ap_shutdown_conn	(	conn_rec *	c,
		int	flush
	)

Shutdown the connection for writing.

Parameters

c	The connection to shutdown
flush	Whether or not to flush pending data before

Returns

APR_SUCCESS or the underlying error

ap_start_lingering_close()

int ap_start_lingering_close

(

conn_rec *

c

)

create_connection()

conn_rec* create_connection	(	apr_pool_t *	p,
		server_rec *	server,
		apr_socket_t *	csd,
		long	conn_id,
		void *	sbh,
		apr_bucket_alloc_t *	alloc
	)

create_connection is a RUN_FIRST hook which allows modules to create connections. In general, you should not install filters with the create_connection hook. If you require vhost configuration information to make filter installation decisions, you must use the pre_connection or install_network_transport hook. This hook should close the connection if it encounters a fatal error condition.

Parameters

p	The pool from which to allocate the connection record
server	The server record to create the connection too.
csd	The socket that has been accepted
conn_id	A unique identifier for this connection. The ID only needs to be unique at that time, not forever.
sbh	A handle to scoreboard information for this connection.
alloc	The bucket allocator to use for all bucket/brigade creations

Returns

An allocated connection record or NULL.

create_secondary_connection()

conn_rec* create_secondary_connection	(	apr_pool_t *	p,
		conn_rec *	master,
		apr_bucket_alloc_t *	alloc
	)

create_secondary_connection is a RUN_FIRST hook which allows modules to create secondary connections. In general, you should not install filters with the create_secondary_connection hook. This hook should close the connection if it encounters a fatal error condition.

Parameters

p	The pool for the secondary connection
master	The master connection this belongs to.
alloc	The bucket allocator to use for all bucket/brigade creations

Returns

An allocated connection record or NULL.

pre_close_connection()

int pre_close_connection

(

conn_rec *

c

)

This hook implements different protocols. Before a connection is closed, protocols might have to perform some housekeeping actions, such as sending one last goodbye packet. The connection is, unless some other error already happened before, still open and operational. All pre-close-connection hooks are run until one returns something other than ok or decline

Parameters

c	The connection on which the request has been received.

Returns

OK or DECLINED

pre_connection()

int pre_connection	(	conn_rec *	c,
		void *	csd
	)

This hook gives protocol modules an opportunity to set everything up before calling the protocol handler. All pre-connection hooks are run until one returns something other than ok or decline

Parameters

c	The connection on which the request has been received.
csd	The mechanism on which this connection is to be read. Most times this will be a socket, but it is up to the module that accepts the request to determine the exact type.

Returns

OK or DECLINED

process_connection()

int process_connection

(

conn_rec *

c

)

This hook implements different protocols. After a connection has been established, the protocol module must read and serve the request. This function does that for each protocol module. The first protocol module to handle the request is the last module run.

Parameters

c	The connection on which the request has been received.

Returns

OK or DECLINED

Variable Documentation

ap_bucket_type_eoc

AP_DECLARE_DATA const apr_bucket_type_t ap_bucket_type_eoc

extern

End Of Connection (EOC) bucket