apache中http_connection系列api接口功能翻译

http_connection.h

文件版本2.0

/**
 * @file  http_connection.h
 * @brief Apache connection library//apache连接库
 */

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

 * @param c The connection on which the request is read

 * @param 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

 */

 /**
 * 协议模块驱动，为所有协议模块调用所有预连接和连接钩子。
 * 参数c 请求读取的连接
 * 参数csd 读取连接的机制、途径。
 * 大多数将会是一个socket，也由
 * 接受请求的模块来决定确切的类型
 */
AP_CORE_DECLARE(void) ap_process_connection(conn_rec *c, void *csd);

 

 

 

/**
 * Flushes all remain data in the client send buffer//刷新客户端发送缓存中的所有停留数据
 * @param c The connection to flush//参数 c 要刷新的连接
 */
/**
 * 刷新客户端发送缓存中的所有停留数据
 * 参数 c 要刷新的连接
 */
AP_CORE_DECLARE(void) ap_flush_conn(conn_rec *c);

 

 

 

/**
 * This function is responsible for the following cases
 * <pre>
 * 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://www.ics.uci.edu/pub/ietf/http/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.
 * </pre>
 * @param c The connection we are closing
 */
/**
 * 此函数与下列用例有关：
 * <pre>
 * 现在，我们去从客户端读取直到读取到EOF（文件结束符）或者直到超过MAX_SECS_TO_LINGER （最大停留秒数），这样做的原因可以从此草案中找到证明。
 *
 * http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt
 *
 * 简而言之--如果我们不这样做，有可能在所有响应数据都发送到客户端之前发送卸载此连接的TCP RST 包。
 * 参数c 要结束的连接。
 */
AP_DECLARE(void) ap_lingering_close(conn_rec *c);

 

 

 

  /* Hooks */钩子
/**
 * 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.
 * @param p The pool from which to allocate the connection record 

 * @param server The server record to create the connection too.

 * @param csd The socket that has been accepted 

 * @param conn_id A unique identifier for this connection.  The ID only
 *                needs to be unique at that time, not forever.

 * @param sbh A handle to scoreboard information for this connection. 

 * @param alloc The bucket allocator to use for all bucket/brigade creations

 * @return An allocated connection record or NULL.

 */

 

/**
  * create_connection是一个允许模块们创建连接的预启动钩子。一般来说，不应为该钩子安装过滤器。

 * 如果你需要虚机主机配置信息来制作过滤器安装指令，你必须使用pre_connection或者install_network_transport挂钩。
 * 参数p--分配连接集的内存池。
 * 参数server--创建连接的服务器集。
 * 参数csd--接受的socket
 * 参数 conn_id 此连接的一个唯一标识。在那时必须是唯一的，不要求永远唯一。
 * 参数sbh 为此连接打分的句柄
 * 参数alloc 用来创建所有bucket/brigade（队列）的 bucket分配器。
 * 返回一个分配的连接集。
 */

 

AP_DECLARE_HOOK(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))
  

 

 

 

/**
 * 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

 * @param c The connection on which the request has been received.

 * @param 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.
 * @return OK or DECLINED
 */

 

/**
 * 此钩子使所有协议模块在调用协议句柄之前准备好所需。所有预连接钩子都会运行直到模块除了返回可以或拒绝之外返回别的东西。
 * 参数c--承认的请求连接
 * 参数csd--读取连接的途径。
 * 大多数将会是一个socket，也由接受请求的模块来决定确切的类型
 * 返回可以或拒绝

 */
AP_DECLARE_HOOK(int,pre_connection,(conn_rec *c, void *csd))

 

 

 

 

/**
 * 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.

 * @param c The connection on which the request has been received.

 * @return OK or DECLINED

 */

/**
 * 此钩子实现不同协议。在一个连接建立之后，该协议模块必须读取和伺服该请求。此函数对每一个协议模块起作用。最先处理此请求的协议模块会是最后运行的模块。
 * 参数c--承认请求的连接
 * 返回可以或拒绝
 */
AP_DECLARE_HOOK(int,process_connection,(conn_rec *c))

 

 

 

 

 

 

/** End Of Connection (EOC) bucket */连接结束桶。。

 

AP_DECLARE_DATA extern const apr_bucket_type_t ap_bucket_type_eoc;

 

 

/**
 * Determine if a bucket is an End Of Connection (EOC) bucket 测试一个桶是否为端连接桶。。
 * @param e The bucket to inspect 参数e 要检查的桶
 * @return true or false返回正确或错误
 */
#define AP_BUCKET_IS_EOC(e)         (e->type == &ap_bucket_type_eoc)

 

 

/**
 * Make the bucket passed in an End Of Connection (EOC) bucket使一个桶进入端连接桶。。
 * @param b The bucket to make into an EOC bucket参数b--要成为端连接桶的桶。
 * @return The new bucket, or NULL if allocation failed返回新的桶，如果分配失败返回NULL
 */
AP_DECLARE(apr_bucket *) ap_bucket_eoc_make(apr_bucket *b);

 

 

 

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

 * 创建一个端连接桶（队列），涉及需要关闭的连接。
 * @param list The freelist from which this bucket should be allocated参数list--分配桶的自由空间
 * @return The new bucket, or NULL if allocation failed返回新的桶，分配失败返回NULL
 */
AP_DECLARE(apr_bucket *) ap_bucket_eoc_create(apr_bucket_alloc_t *list);