/*
 * Copyright 1999-2006 University of Chicago
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#if !defined GLOBUS_XIO_DRIVER_HTTP_H
#define GLOBUS_XIO_DRIVER_HTTP_H 1

/**
 * @file globus_xio_http.h
 * @brief Globus XIO HTTP Driver Header
 */
#include "globus_xio.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup globus_xio_http_driver Globus XIO HTTP Driver
 * @ingroup globus_xio
 * @brief Globus XIO HTTP Driver
 *
 * This driver implements the HTTP/1.0 and HTTP/1.1 protocols within
 * the Globus XIO framework. It may be used with the tcp driver for
 * the standard HTTP protocol stack, or may be combined with the gsi
 * driver for a HTTPS implementation.
 *
 * This implementation supports user-defined HTTP headers, persistent
 * connections, and chunked transfer encoding.
 */

/**
 * @defgroup globus_xio_http_driver_instance Opening/Closing
 * @ingroup globus_xio_http_driver
 * @brief Opening/Closing
 *
 * An XIO handle with the http driver can be created with either 
 * @ref globus_xio_handle_create() or
 * @ref globus_xio_server_register_accept().
 *
 * If the handle is created with
 * @ref globus_xio_server_register_accept(), then an HTTP service handle
 * will be created when @ref globus_xio_register_open() is called. The XIO
 * application must call one of the functions in the @ref globus_xio_read()
 * family to receive the HTTP request metadata. This metadata will be returned
 * in the data descriptor associated with that first read: the application
 * should use the GLOBUS_XIO_HTTP_GET_REQUEST descriptor cntl to extract
 * this metadata.
 *
 * If the handle is created with @ref globus_xio_handle_create(), then
 * an HTTP client handle will be created when
 * @ref globus_xio_register_open() is called. HTTP request headers, version and
 * method may be chosen by setting attributes.
 */

/**
 * @defgroup globus_xio_http_driver_io Reading/Writing
 * @ingroup globus_xio_http_driver
 * @brief Reading/Writing
 *
 * The HTTP driver behaves similar to the underlying transport driver
 * with respect to reads and writes with the exception that metadata must
 * be passed to the handle via open attributes on the client side and will
 * be received as data descriptors as part of the first request read or
 * response read.
 */

/**
 * @defgroup globus_xio_http_driver_server Server
 * @ingroup globus_xio_http_driver
 * @brief Server
 *
 * The @ref globus_xio_server_create() causes a new transport-specific
 * listener socket to be created to handle new HTTP connections.
 * @ref globus_xio_server_register_accept() will accept a new
 * connection for processing. @ref globus_xio_server_register_close()
 * cleans up the internal resources associated with the http server
 * and calls close on the listener.
 *
 * Multiple HTTP requests may be read in sequence from an HTTP
 * server. After each request is processed and the response is sent (either by
 * writing the entire entity body as specified by the Content-Length header or 
 * by using the GLOBUS_XIO_HTTP_HANDLE_SET_END_OF_ENTITY handle cntl), the next
 * read will contain the metadata related to the next operation.
 * Only one request will be in process at once--the previous request must have
 * sent or received and EOF (whichever is applicable to the request type).
 */

/**
 * @defgroup globus_xio_http_driver_cntls Attributes and Cntls
 * @ingroup globus_xio_http_driver
 * @brief Attributes and Cntls
 * 
 * HTTP driver specific attrs and cntls.
 * 
 * @see globus_xio_attr_cntl()
 * @see globus_xio_handle_cntl()
 */

/**
 * @defgroup globus_xio_http_driver_errors Error Types
 * @ingroup globus_xio_http_driver
 * @brief Error Types
 *
 * In addition to errors generated by underlying protocol drivers, the XIO
 * HTTP driver defines a few error conditions specific to the HTTP protocol.
 *
 * @see globus_xio_driver_error_match()
 */
/** doxygen varargs filter stuff
 * GlobusVarArgDefine(
 *      attr, globus_result_t, globus_xio_attr_cntl, attr, driver)
 * GlobusVarArgDefine(
 *      handle, globus_result_t, globus_xio_handle_cntl, handle, driver)
 * GlobusVarArgDefine(
 *      dd, globus_result_t, globus_xio_data_descriptor_cntl, dd, driver)
 */

/**
 * @brief HTTP Header
 * @ingroup globus_xio_http_driver
 */
typedef struct
{
    /** Header Name */
    char *                              name;
    /** Header Value */
    char *                              value;
}
globus_xio_http_header_t;

/**
 * HTTP driver specific cntls
 * @ingroup globus_xio_http_driver_cntls
 */
typedef enum
{
    /**
     * GlobusVarArgEnum(handle)
     * Set the value of a response HTTP header. 
     * @ingroup globus_xio_http_driver_cntls
     *
     * @param header_name
     *        Name of the HTTP header to set.
     * @param header_value
     *        Value of the HTTP header
     *
     * Certain headers will cause changes in how the HTTP protocol will
     * be handled. These include:
     * - Transfer-Encoding: {identity|chunked}
     *   Override the default transfer encoding. If a server knows the
     *   exact length of the message body, or does not intend to support
     *   persistent connections, it may set this header to be
     *   "identity".<br><br>
     *   If this is set to "identity" and any of the following are true, then
     *   the connection will be closed after the end of the response is sent:
     *   <br><br>
     *   - A Content-Length header is not present
     *   - The HTTP version is set to "HTTP/1.0"
     *   - The Connection header is set to "close"
     *   Attempts to set this to "chunked" with an "HTTP/1.0" client will
     *   fail with a GLOBUS_XIO_ERROR_HTTP_INVALID_HEADER error.
     * - Content-Length: 1*Digit
     *   - Provide a content length for the response message. If the 
     *     "chunked" transfer encoding is being used, then this header
     *     will be silently ignored by the HTTP driver.
     * - Connection: close
     *   - The HTTP connection will be closed after the end of the data
     *     response is written.
     *
     * @return This handle control function can fail with
     * - GLOBUS_XIO_ERROR_MEMORY
     * - GLOBUS_XIO_ERROR_PARAMETER 
     * - GLOBUS_XIO_ERROR_HTTP_INVALID_HEADER
     */
    /* const char *                     header_name,
       const char *                     header_value */
    GLOBUS_XIO_HTTP_HANDLE_SET_RESPONSE_HEADER,
    /** GlobusVarArgEnum(handle)
     * Set the response status code.
     * @ingroup globus_xio_http_driver_cntls
     *
     * @param status
     * Value in the range 100-599 which will be used as the HTTP response
     * code, as per RFC 2616.
     *
     * If this cntl is not called by a server, then
     * the default value of 200 ("Ok") will be used. If this is called on the
     * client-side of an HTTP connection, the handle control will fail with a
     * GLOBUS_XIO_ERROR_PARAMETER error.
     *
     * @return This handle control function can fail with
     * - GLOBUS_XIO_ERROR_PARAMETER 
     */
    /* int status */
    GLOBUS_XIO_HTTP_HANDLE_SET_RESPONSE_STATUS_CODE,
    /** GlobusVarArgEnum(handle)
     * Set the response reason phrase.
     * @ingroup globus_xio_http_driver_cntls
     *
     * @param reason
     *        The value of the HTTP response string, as per RFC 2616.
     *
     * If this cntl is not called by a server, then a default value based on
     * the handle's response status code will be generated. If this is called
     * on the client-side of an HTTP connection, the handle control will fail
     * with a GLOBUS_XIO_ERROR_PARAMETER error.
     *
     * @return This handle control function can fail with
     * - GLOBUS_XIO_ERROR_MEMORY
     * - GLOBUS_XIO_ERROR_PARAMETER 
     */
    /* const char * reason */
    GLOBUS_XIO_HTTP_HANDLE_SET_RESPONSE_REASON_PHRASE,
    /** GlobusVarArgEnum(handle)
     * Set the response HTTP version.
     * @ingroup globus_xio_http_driver_cntls
     *
     * @param version
     *        The HTTP version to be used in the server response line.
     *
     * If this cntl is not called by a server, then the default of
     * GLOBUS_XIO_HTTP_VERSION_1_1 will be used, though no HTTP/1.1 features 
     * (chunking, persistent connections, etc) will be
     * assumed if the client request was an HTTP/1.0 request. If this is
     * called on the client-side of an HTTP connection, the handle control
     * will fail with GLOBUS_XIO_ERROR_PARAMETER.
     *
     * @return This handle control function can fail with
     * - GLOBUS_XIO_ERROR_MEMORY
     * - GLOBUS_XIO_ERROR_PARAMETER
     */
    /* globus_xio_http_version_t version */
    GLOBUS_XIO_HTTP_HANDLE_SET_RESPONSE_HTTP_VERSION,
    /** GlobusVarArgEnum(handle)
     * Indicate end-of-entity for an HTTP body.
     * @ingroup globus_xio_http_driver_cntls
     *
     * HTTP clients and servers must call this command to indicate to the
     * driver that the entity-body which is being sent is completed.
     * Subsequent attempts to write data on the handle will fail.
     *
     * This handle command MUST be called on the client side of an HTTP
     * connection when the HTTP method is OPTIONS, POST, or PUT, or when
     * the open attributes indicate that an entity will be sent. This handle
     * command MUST be called on the server side of an HTTP request connection
     * when the HTTP method was OPTIONS, GET, POST, or TRACE.
     */
    GLOBUS_XIO_HTTP_HANDLE_SET_END_OF_ENTITY,
    GLOBUS_XIO_HTTP_HANDLE_SET_REQUEST_HEADER
}
globus_xio_http_handle_cmd_t;

/**
 * HTTP driver specific attribute and data descriptor cntls
 * @ingroup globus_xio_http_driver_cntls
 */
typedef enum
{
    /** GlobusVarArgEnum(attr)
     * Set the HTTP method to use for a client request.
     * @ingroup globus_xio_http_driver_cntls
     *
     * @param method
     *        The request method string ("GET", "PUT", "POST", etc) that will
     *        be used in the HTTP request.
     *
     * If this is not set on the target before it is opened, it will default
     * to GET.
     *
     * This attribute is ignored when opening the server side of an HTTP
     * connection.
     *
     * Setting this attribute may fail with
     * - GLOBUS_XIO_ERROR_MEMORY
     * - GLOBUS_XIO_ERROR_PARAMETER
     */
    /* const char * method */
    GLOBUS_XIO_HTTP_ATTR_SET_REQUEST_METHOD,
    /** GlobusVarArgEnum(attr)
     * Set the HTTP version to use for a client request.
     * @ingroup globus_xio_http_driver_cntls
     *
     * @param version 
     * The HTTP version to use for the client request.
     *
     * If the client is using HTTP/1.0 in a request which will send a
     * request message body (such as a POST or PUT), then the client MUST set
     * the "Content-Length" HTTP header to be the length of the message. If
     * this attribute is not present, then the default of
     * GLOBUS_XIO_HTTP_VERSION_1_1 will be used.
     *
     * This attribute is ignored when opening the server side of an HTTP
     * connection.
     */
    /* globus_xio_http_version_t version */
    GLOBUS_XIO_HTTP_ATTR_SET_REQUEST_HTTP_VERSION,
    /** GlobusVarArgEnum(attr)
     * Set the value of an HTTP request header. 
     * @ingroup globus_xio_http_driver_cntls
     *
     * @param header_name
     *        Name of the HTTP header to set.
     * @param header_value
     *        Value of the HTTP header
     *
     * Certain headers will cause the HTTP driver to behave differently than
     * normal. This must be called before
     *
     * - Transfer-Encoding: {identity|chunked}
     *   Override the default transfer encoding. If a server knows the
     *   exact length of the message body, or does not intend to support
     *   persistent connections, it may set this header to be
     *   "identity".<br><br>
     *   If this is set to "identity" and any of the following are true, then
     *   the connection will be closed after the end of the message is sent:
     *   <br><br>
     *     - A Content-Length header is not present
     *     - The HTTP version is set to "HTTP/1.0"
     *     - The Connection header is set to "close"
     *   Attempts to set this to "chunked" with an "HTTP/1.0" client will
     *   fail with a GLOBUS_XIO_ERROR_HTTP_INVALID_HEADER error.
     * - Content-Length: 1*Digit
     *   - Provide a content length for the response message. If the 
     *     "chunked" transfer encoding is being used, then this header
     *     will be silently ignored by the HTTP driver.
     * - Connection: close
     *   - If present in the server response, the connection
     *     will be closed after the end of the data response is written.
     *     Otherwise, when persistent connections are enabled, the connection
     *     <em>may</em> be left open by the driver. Persistent connections
     *     are not yet implemented.
     */
    /* const char *                     header_name,
     * const char *                     header_value */
    GLOBUS_XIO_HTTP_ATTR_SET_REQUEST_HEADER,
    /** GlobusVarArgEnum(attr)
     * Delay writing HTTP request until first data write.
     *
     * If this attribute is present when opening an HTTP handle, the HTTP
     * request will not be sent immediately upon opening the handle. Instead,
     * it will be delayed until the first data write is done. This allows
     * other HTTP headers to be sent after the handle is opened.
     * 
     * This attribute cntl takes no arguments.
     */
    GLOBUS_XIO_HTTP_ATTR_DELAY_WRITE_HEADER,
    /** GlobusVarArgEnum(dd)
     * Get HTTP Request Information.
     *
     * Returns in the passed parameters values concerning the HTTP request. Any
     * of the parameters may be NULL if the application is not interested in
     * that part of the information.
     *
     * @param method
     *      Pointer to be set to the HTTP request method (typically
     *      GET, PUT, or POST). The caller must not access this value
     *      outside of the lifetime of the data descriptor nor free it.
     * @param uri
     *      Pointer to be set to the requested HTTP path. The caller must
     *      not access this value outside of the lifetime of the data
     *      descriptor nor free it.
     * @param http_version
     *      Pointer to be set to the HTTP version used for this request.
     * @param headers
     *      Pointer to be set to point to a hashtable of
     *      globus_xio_http_header_t values, keyed by the HTTP header names.
     *      The caller must not access this value outside of the lifetime of
     *      the data descriptor nor free it or any values in it.
     */
    /* char **                          method,
       char **                          uri,
       globus_xio_http_version_t *      http_version,
       globus_hashtable_t *             headers */
    GLOBUS_XIO_HTTP_GET_REQUEST,
    /** GlobusVarArgEnum(dd)
     * Get HTTP Response Information
     *
     * Returns in the passed parameters values concerning the HTTP response.
     * Any of the parameters may be NULL if the application is not interested
     * in that part of the information.
     *
     * @param status_code
     *      Pointer to be set to the HTTP response status code (such as 404),
     *      as per RFC 2616. The caller must not access this value outside of
     *      the lifetime of the data descriptor nor free it or any values in
     *      it.
     * @param reason_phrase
     *      Pointer to be set to the HTTP response reason phrase (such as Not
     *      Found). The caller must not access this value outside of
     *      the lifetime of the data descriptor nor free it or any values in
     *      it.
     * @param http_version
     *      Pointer to be set to the HTTP version used for this request.
     * @param headers
     *      Pointer to be set to point to a hashtable of
     *      globus_xio_http_header_t values, keyed by the HTTP header names.
     *      The caller must not access this value outside of the lifetime of
     *      the data descriptor nor free it or any values in it.
     */
    /* int *                            status_code,
       char **                          reason_phrase,
       globus_xio_http_version_t *      http_version,
       globus_hashtable_t *             headers */
    GLOBUS_XIO_HTTP_GET_RESPONSE

}
globus_xio_http_attr_cmd_t;

/**
 * Error types used to generate errors using the globus_error_generic module.
 * @ingroup globus_xio_http_driver_errors
 */
typedef enum
{
    /**
     * An attempt to set a header which is not compatible with the HTTP
     * version being used.
     * @hideinitializer
     */
    GLOBUS_XIO_HTTP_ERROR_INVALID_HEADER,
    /**
     * Error parsing HTTP protocol
     */
    GLOBUS_XIO_HTTP_ERROR_PARSE,
    /**
     * There is no entity body to read or write.
     */
    GLOBUS_XIO_HTTP_ERROR_NO_ENTITY,
    /**
     * Server side fake EOF
     */
    GLOBUS_XIO_HTTP_ERROR_EOF,
    /**
     * Persistent connection dropped by the server.
     */
    GLOBUS_XIO_HTTP_ERROR_PERSISTENT_CONNECTION_DROPPED
}
globus_xio_http_errors_t;

/**
 * @ingroup globus_xio_http_driver
 * Valid HTTP versions, used with the
 * #GLOBUS_XIO_HTTP_ATTR_SET_REQUEST_HTTP_VERSION attribute and the
 * #GLOBUS_XIO_HTTP_HANDLE_SET_RESPONSE_HTTP_VERSION handle control
 */
typedef enum
{
    GLOBUS_XIO_HTTP_VERSION_UNSET,
    /**
     * HTTP/1.0
     */
    GLOBUS_XIO_HTTP_VERSION_1_0,
    /**
     * HTTP/1.1
     */
    GLOBUS_XIO_HTTP_VERSION_1_1
}
globus_xio_http_version_t;

#ifdef __cplusplus
}
#endif

#endif