rmlibhttp.h

Dag Erling http library source code

/*-
 * Copyright (c) 1998-2004 Dag-Erling Co飀an Sm鴕grav
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer
 *    in this position and unchanged.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * $FreeBSD: src/lib/libfetch/fetch.h,v 1.26 2004/09/21 18:35:20 des Exp $
 */

/**
 * @file rmlibhttp.h
 * @brief HTTP library, based on the FreeBSD libfetch.
 *
 * This library can be used to retrieved files from a HTTP server, allowing the
 * client to seek. It can be used in cached mode to minimize the number of HTTP
 * request sent over the wire when a file is not read in linear mode, but
 * accessed randomly. In this case, the library will involve an extra memcpy.
 * 
 * <pre>
 * 
 * Copyright (c) 1998-2004 Dag-Erling Co飀an Sm鴕grav
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer
 *    in this position and unchanged.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * </pre>
 * 
 * @author Julien Lerouge (for Sigma Designs extensions only)
 * @date   2005-03-31
 */ 


#ifndef _FETCH_H_INCLUDED
#define _FETCH_H_INCLUDED

#ifndef ALLOW_OS_CODE
#define ALLOW_OS_CODE 1
#endif

#include "../../rmdef/rmdef.h"

RM_EXTERN_C_BLOCKSTART

#include "../../rmlibcw/include/rmlibcw.h"
#include "../../rmcore/include/rmcore.h"

/** Lib fetch version */
#define _LIBFETCH_VER "libfetch/2.0/Sigma"

/** HTTPFile handle opaque */
struct http_file;
typedef struct http_file HTTPFile;

/**
 * @brief HTTP flags
 *
 * Flags suitable for fetchOpen :
 * 	- RM_HTTP_NO_PROXY : don't use any proxy. By default, tries to get the
 * 	  proxy from the environment (HTTP_PROXY)
 * 	- RM_HTTP_VERBOSE : be more verbose
 * 	- RM_HTTP_IPV4 : defaultm use IPV4
 * 	- RM_HTTP_IPV6 : use IPV6 when opening sockets (if supported)
 * 	- RM_HTTP_NO_REDIRECT : don't allow any redirection
 *	- RM_HTTP_OPEN_CACHED : open an URL in cached mode (default uncached)
 * <pre>
 *
 *       When a URL is opened in cached mode, a small amount of memory is
 *       malloced to store data, so that several HTTP request on the same data
 *       range only generate one real request on the wire. Access to the file
 *       is then divided into chunks. Each chunk has the size of one line of
 *       the cache. This mode is useful when seeking is often required on a
 *       file, or when a file needs random access. It requires a HTTP 1.1
 *       server, since it will pipeline several requests on one connection.
 *
 *       For example in cached mode, if one line of cache is 128KB, reading
 *       from offset 125KB to 148KB would require two HTTP request (on the
 *       same connection) :
 *               1. 0 -> 128 KB
 *               2. 128 -> 256 KB
 *
 *       Another read for the range 32KB to 64Kb would not require sending
 *       any other HTTP request.
 *
 *       In regular mode, each time a seek is needed or each time linear
 *       reading of the file needs to be broken, a new HTTP connection and a
 *       new HTTP request is required.
 *
 * </pre> 
 *	- RM_HTTP_CUSTOM_HEADER : if this flag is set, then the next call to
 *	  fetchOpen will use the custom header, set with the function
 *	  fetchSetCustomHeader, as an additionnal header in the HTTP request
 *	  for all the request on this URL (useful for custom DRM header for
 *	  example). The custom header is duplicated with a malloc for each
 *	  fetchOpen.
 */
typedef enum {
	RM_HTTP_NO_PROXY	=	 1,
	RM_HTTP_VERBOSE		=	 2,
	RM_HTTP_IPV4		=	 4,
	RM_HTTP_IPV6		= 	 8,
	RM_HTTP_NO_REDIRECT	=	16,
	RM_HTTP_OPEN_CACHED     =    	32,
	RM_HTTP_CUSTOM_HEADER	=	64,
	RM_HTTP_CUSTOM_HOOKS	=      128
}RMHTTPFlags;

/** @defgroup shemes Recognized schemes*/
/* @{ */
/** 
 * ftp is only there in case a redirection from a HTTP server to a FTP server
 * happens
 */
#define SCHEME_FTP	"ftp"
/** HTTP scheme, used to identify HTTP URL */
#define SCHEME_HTTP	"http"
/** HTTPS scheme, used to identify HTTPS URL */
#define SCHEME_HTTPS	"https"
/* @} */


/** @defgroup errors Error codes */
/* @{ */
#define	FETCH_ABORT	 1 	/**< Connection reset or aborted */
#define	FETCH_AUTH	 2	/**< Auth required or bad auth */
#define	FETCH_DOWN	 3	/**< Connection refused or host down */
#define	FETCH_EXISTS	 4	/**< Already exist */
#define	FETCH_FULL	 5	/**< No more space */
#define	FETCH_INFO	 6	/**< Info */
#define	FETCH_MEMORY	 7	/**< No more memory */
#define	FETCH_MOVED	 8	/**< Moved */
#define	FETCH_NETWORK	 9	/**< Network error */
#define	FETCH_OK	10	/**< No error */
#define	FETCH_PROTO	11	/**< Protocol error */
#define	FETCH_RESOLV	12	/**< Resolver error */
#define	FETCH_SERVER	13	/**< Internal server error */
#define	FETCH_TEMP	14	/**< Service unavailable */
#define	FETCH_TIMEOUT	15	/**< Timeout */
#define	FETCH_UNAVAIL	16	/**< Not available */
#define	FETCH_UNKNOWN	17	/**< Unknown error */
#define	FETCH_URL	18	/**< Bad URL */
#define	FETCH_VERBOSE	19	/**< Verbose */
#define	FETCH_PIPE	20	/**< Connection closed by peer */
/* @} */

/** @defgroup cache Cache parameters */
/* @{ */
/** Size of one line in the cache, log2 */
#define CACHELOG2 17 			//128K
/** Size of one line in the cache (bytes) */
#define CACHEBUFFERSIZE (1<<CACHELOG2)
/** Number of lines in one cache, must be < 32 */
#define CACHENBUFFER 8
/* @} */

/**
   For custom http hooks: open, close, reopen, seek, pre-read, and post-read operations.
   Suitable for use with link-level decryption.
   Your functions should return -1 to indicate an error, and 0 otherwise.
*/
typedef RMint32 (*HttpOpenHookOp) (void *cookie);
typedef RMint32 (*HttpCloseHookOp) (void *cookie);
typedef RMint32 (*HttpReopenHookOp) (void *cookie);
typedef RMint32 (*HttpSeekHookOp) (void *cookie, RMint64 position, RMint32 whence);
typedef RMint32 (*HttpPreReadHookOp) (void *cookie, RMuint8 *buffer, RMint32 length);
typedef RMint32 (*HttpPostReadHookOp) (void *cookie, RMuint8 *buffer, RMint32 length, RMint32 *more_data);

/**
   For custom http hooks, hook operations struct
*/
typedef struct {
	HttpOpenHookOp     open;
	HttpCloseHookOp    close;
	HttpReopenHookOp   reopen;
	HttpSeekHookOp     seek;
	HttpPreReadHookOp  preread;
	HttpPostReadHookOp postread;
} HttpHookOps;

/**
 * Set custom hooks. The custom hooks will be used if the
 * RM_HTTP_CUSTOM_HOOKS flag is set during the fetchOpen.
 *
 * @param cookie - cookie used by the hooks.
 * @param hooks - set of custom callbacks that use the cookie.
 * @return void
 */
RM_LIBRARY_IMPORT_EXPORT void fetchSetCustomHooks(void *cookie, HttpHookOps *hooks);

/**
 * Set custom headers. The custom headers will be used if the
 * RM_HTTP_CUSTOM_HEADER flag is set during the fetchOpen.
 *
 * @param header - custom header, should use "\r\n" as end of line, NULL
 *                 terminated. The final "\r\n" will be added upon sending over
 *                 the wire.  This string will be duplicated by each fetchOpen,
 *                 so it should ne be freed before the fetchOpen.
 * @return void
 */
RM_LIBRARY_IMPORT_EXPORT void fetchSetCustomHeader(RMascii *header);

/** 
 * Open a URL, returns a HTTPFile * or NULL on error.
 * 
 * flags can be a bitwise-or'd combination of the RMHTTPFlags.
 
 * @param URL - URL to open
 * @param flags - flags for this URL
 * @return HTTPFile, NULL on error.
 */
RM_LIBRARY_IMPORT_EXPORT HTTPFile * fetchOpen(const RMascii *URL, RMHTTPFlags flags);

/**
 * Get the current position in a HTTP stream (if possible)
 *
 * @param file - opened HTTP stream
 * @return RMint64 position, -1 on error
 */
RM_LIBRARY_IMPORT_EXPORT RMint64 fetchTell(HTTPFile * file);

/**
 * Seek in a HTTP stream
 *
 * @param file - opened HTTP stream
 * @param offset - seek position
 * @param whence - reference for the position, can be RM_FILE_SEEK_START,
 *                 RM_FILE_SEEK_CURRENT, or RM_FILE_SEEK_END.
 * @return 0 on success, -1 on error
 */
RM_LIBRARY_IMPORT_EXPORT RMint32 fetchSeek(HTTPFile * file, RMint64 offset, RMint32 whence);

/**
 * Read from a HTTP stream
 *
 * @param file - opened HTTP stream
 * @param buf
 * @param size
 * @return 0 on EOF, -1 on error, number of bytes read else
 */
RM_LIBRARY_IMPORT_EXPORT RMint32 fetchRead(RMuint8 *buf, RMint32 size, HTTPFile * file);

/**
 * Close a HTTP stream
 *
 * @param file - opened HTTP strea
 * @return -1 on error, 0 on success
 */
RM_LIBRARY_IMPORT_EXPORT RMint32 fetchClose(HTTPFile * file);

/** Exported symbol, suitable for use with RMOpenFileCookie, see rmfile.h */
RM_LIBRARY_IMPORT_EXPORT extern void *httpFileOps;


/** Last HTTP error code */
RM_LIBRARY_IMPORT_EXPORT extern RMint32		 fetchLastErrCode;

#define MAXERRSTRING 256
/** Last HTTP error string */
RM_LIBRARY_IMPORT_EXPORT extern RMascii		 fetchLastErrString[MAXERRSTRING];

/** I/O timeout */
RM_LIBRARY_IMPORT_EXPORT extern RMint32		 fetchTimeout;

/** Restart interrupted syscalls */
RM_LIBRARY_IMPORT_EXPORT extern RMint32		 fetchRestartCalls;

RM_EXTERN_C_BLOCKEND

#endif