ShuriZma
/
RetroArch
mirror of https://github.com/libretro/RetroArch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

http_lib.c - Add documentation

This commit is contained in:
twinaphex 2015-01-21 00:01:01 +01:00
parent 6afd5684ec
commit c27021e90f
2 changed files with 198 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
http_lib.c
View File

@ -62,18 +62,19 @@ int http_proxy_port=0;
/* user agent id string */ /* user agent id string */
static const char *http_user_agent="adlib/3 ($Date: 1998/09/23 06:19:15 $)"; static const char *http_user_agent="adlib/3 ($Date: 1998/09/23 06:19:15 $)";
/* /**
* read a line from file descriptor * http_read_line:
* @fd : File descriptor to read from.
* @buffer : Placeholder for data.
* @max : Maximum number of bytes to read.
*
* Reads a line from file descriptor
* returns the number of bytes read. negative if a read error occured * returns the number of bytes read. negative if a read error occured
* before the end of line or the max. * before the end of line or the max.
* cariage returns (CR) are ignored. * cariage returns (CR) are ignored.
*/ *
* Returns: number of bytes read, negative if error occurred.
/* **/
* fd - file descriptor to read from
* buffer - placeholder for data
* max - max number of bytes to read
*/
static int http_read_line (int fd, char *buffer, int max) static int http_read_line (int fd, char *buffer, int max)
{ {
/* not efficient on long lines (multiple unbuffered 1 char reads) */ /* not efficient on long lines (multiple unbuffered 1 char reads) */
@ -98,18 +99,19 @@ static int http_read_line (int fd, char *buffer, int max)
} }
/* /**
* read data from file descriptor * http_read_buffer:
* retries reading until the number of bytes requested is read. * @fd : File descriptor to read from.
* returns the number of bytes read. negative if a read error (EOF) occured * @buffer : Placeholder for data.
* @max : Maximum number of bytes to read.
*
* Reads data from file descriptor.
* Retries reading until the number of bytes requested is read.
* Returns the number of bytes read. negative if a read error (EOF) occured
* before the requested length. * before the requested length.
*/ *
/* * Returns: number of bytes read, negative if error occurred.
* fd - file descriptor to read from **/
* buffer - placeholder for data
* max - max number of bytes to read
*/
static int http_read_buffer (int fd, char *buffer, int length) static int http_read_buffer (int fd, char *buffer, int length)
{ {
int n,r; int n,r;
@ -121,14 +123,17 @@ static int http_read_buffer (int fd, char *buffer, int length)
return -n; return -n;
buffer += r; buffer += r;
} }
return n; return n;
} }
typedef enum typedef enum
{ {
CLOSE, /* Close the socket after the query (for put) */ /* Close the socket after the query (for put) */
KEEP_OPEN /* Keep it open */ CLOSE,
/* Keep it open */
KEEP_OPEN
} querymode; } querymode;
#ifndef OSK #ifndef OSK
@ -143,25 +148,28 @@ static http_retcode http_query(const char *command, const char *url,
#define MAXBUF 512 #define MAXBUF 512
/* /*
* Pseudo general http query * http_query:
* @command : Command to send.
* @url : URL / filename queried.
* @additional_header : Additional header.
* @mode : Type of query.
* @data : Data to send after header. If NULL,
* no data is sent.
* @length : Size of data.
* @pfd : Pointer to variable where to set file
* descriptor value.
* *
* send a command and additional headers to the http server. * Pseudo general HTTP query.
*
* Sends a command and additional headers to the HTTP server.
* optionally through the proxy (if http_proxy_server and http_proxy_port are * optionally through the proxy (if http_proxy_server and http_proxy_port are
* set). * set).
* *
* Limitations: the url is truncated to first 256 chars and * Limitations: the url is truncated to first 256 chars and
* the server name to 128 in case of proxy request. * the server name to 128 in case of proxy request.
*/ *
* Returns: HTTP return code.
/* **/
command - command to send
url - url / filename queried
additional_header - additional header
mode - type of query
data - Data to send after header. If NULL, not data is sent
length - size of data
pfd - pointer to variable where to set file descriptor value
*/
static http_retcode http_query(const char *command, const char *url, static http_retcode http_query(const char *command, const char *url,
const char *additional_header, querymode mode, const char *additional_header, querymode mode,
const char *data, int length, int *pfd) const char *data, int length, int *pfd)
@ -262,7 +270,15 @@ static http_retcode http_query(const char *command, const char *url,
} }
/* /**
* http_put:
* @filename : Name of the resource to create.
* @data : Pointer to the data to send.
* @length : Length of the data to send.
* @overwrite : Flag to request to overwrite the
* resource if it already exists.
* @type : Type of data.
*
* Put data on the server * Put data on the server
* *
* This function sends data to the http data server. * This function sends data to the http data server.
@ -271,16 +287,9 @@ static http_retcode http_query(const char *command, const char *url,
* *
* limitations: filename is truncated to first 256 characters * limitations: filename is truncated to first 256 characters
* and type to 64. * and type to 64.
*/ *
* Returns: HTTP return code.
/* **/
filename - name of the ressource to create
data - pointer to the data to send
length - length of the data to send
overwrite - flag to request to overwrite the ressource if it
was already existing.
type - type of the data, if NULL default type is used.
*/
http_retcode http_put(const char *filename, const char *data, http_retcode http_put(const char *filename, const char *data,
int length, int overwrite, const char *type) int length, int overwrite, const char *type)
{ {
@ -295,30 +304,29 @@ http_retcode http_put(const char *filename, const char *data,
} }
/* /**
* Get data from the server * http_get:
* @filename : Name of the resource to create.
* @pdata : Address of pointer which will be set
* to point toward allocated memory containing
* read data.
* @typebuf : Allocated buffer where the read data
* type is returned. If NULL, the type is
* not returned.
*
* Gets data from the server
* *
* This function gets data from the http data server. * This function gets data from the http data server.
* The data is read from the ressource named filename. * The data is read from the ressource named filename.
* Address of new new allocated memory block is filled in pdata * Address of new new allocated memory block is filled in pdata
* whose length is returned via plength. * whose length is returned via plength.
* *
* returns a negative error code or a positive code from the server * Returns a negative error code or a positive code from the server
*
* *
* limitations: filename is truncated to first 256 characters * limitations: filename is truncated to first 256 characters
*/ *
* Returns: HTTP error code.
/* **/
filename - name of the ressource to read
pdata - address of a pointer variable which will be set
to point toward allocated memory containing read data.
plength - address of integer variable which will be set to
length of the read data.
typebuf - allocated buffer where the read data type is returned.
If NULL, the type is not returned.
*/
http_retcode http_get(const char *filename, http_retcode http_get(const char *filename,
char **pdata, int *plength, char *typebuf) char **pdata, int *plength, char *typebuf)
{ {
@ -391,25 +399,27 @@ http_retcode http_get(const char *filename,
} }
/* /**
* Request the header * http_head:
* @filename : Name of the resource to create.
* @plength : Address of integer variable which will be set
* to length of the data.
* @typebuf : Allocated buffer where the read data
* type is returned. If NULL, the type is
* not returned.
*
* Requests the header.
* *
* This function outputs the header of thehttp data server. * This function outputs the header of thehttp data server.
* The header is from the ressource named filename. * The header is from the ressource named filename.
* The length and type of data is eventually returned (like for http_get(3)) * The length and type of data is eventually returned (like for http_get(3))
* *
* returns a negative error code or a positive code from the server * Returns a negative error code or a positive code from the server
* *
* limitations: filename is truncated to first 256 characters * limitations: filename is truncated to first 256 characters
*/ *
* Returns: HTTP return code.
/* **/
* filename - name of the ressource to read
* plength - address of integer variable which will be set to
* length of the data.
* typebuf - allocated buffer where the data type is returned.
* If NULL, the type is not returned.
*/
http_retcode http_head(const char *filename, int *plength, char *typebuf) http_retcode http_head(const char *filename, int *plength, char *typebuf)
{ {
/* mostly copied from http_get : */ /* mostly copied from http_get : */
@ -465,35 +475,38 @@ http_retcode http_head(const char *filename, int *plength, char *typebuf)
/* /**
* Delete data on the server * http_delete:
* @filename : Name of the resource to create.
* *
* This function request a DELETE on the http data server. * Deletes data on the server
* *
* returns a negative error code or a positive code from the server * Request a DELETE on the HTTP data server.
*
* Returns a negative error code or a positive code from the server
* *
* limitations: filename is truncated to first 256 characters * limitations: filename is truncated to first 256 characters
*/ *
* Returns: HTTP return code.
/* **/
* filename - name of the ressource to create
*/
http_retcode http_delete(const char *filename) http_retcode http_delete(const char *filename)
{ {
return http_query("DELETE", filename, "", CLOSE, NULL, 0, NULL); return http_query("DELETE", filename, "", CLOSE, NULL, 0, NULL);
} }
/* parses an url : setting the http_server and http_port global variables /**
* http_parse_url:
* @url : Writable copy of an URL.
* @pfilename : Address of a pointer that will be filled with
* allocated filename. The pointer must be equal
* to NULL before calling it or it will be automatically
* freed (free(3)).
* Parses an url : setting the http_server and http_port global variables
* and returning the filename to pass to http_get/put/... * and returning the filename to pass to http_get/put/...
* returns a negative error code or 0 if sucessfully parsed. * returns a negative error code or 0 if sucessfully parsed.
*/ *
* Returns: 0 if successfully parsed, negative error code if not.
/* url - writeable copy of an url **/
* pfilename - address of a pointer that will be filled with allocated filename
* the pointer must be equal to NULL before calling or it will be
* automatically freed (free(3))
*/
http_retcode http_parse_url(char *url, char **pfilename) http_retcode http_parse_url(char *url, char **pfilename)
{ {
char *pc, c; char *pc, c;

94
http_lib.h
View File

@ -58,15 +58,107 @@ typedef enum
/* prototypes */ /* prototypes */
#ifndef OSK #ifndef OSK
/**
* http_put:
* @filename : Name of the resource to create.
* @data : Pointer to the data to send.
* @length : Length of the data to send.
* @overwrite : Flag to request to overwrite the
* resource if it already exists.
* @type : Type of data.
*
* Put data on the server
*
* This function sends data to the http data server.
* The data will be stored under the ressource name filename.
* returns a negative error code or a positive code from the server
*
* limitations: filename is truncated to first 256 characters
* and type to 64.
*
* Returns: HTTP return code.
**/
http_retcode http_put(const char *filename, const char *data, int length, http_retcode http_put(const char *filename, const char *data, int length,
int overwrite, const char *type) ; int overwrite, const char *type) ;
http_retcode http_get(const char *filename, char **pdata,int *plength, char *typebuf); /**
* http_get:
* @filename : Name of the resource to create.
* @pdata : Address of pointer which will be set
* to point toward allocated memory containing
* read data.
* @typebuf : Allocated buffer where the read data
* type is returned. If NULL, the type is
* not returned.
*
* Gets data from the server
*
* This function gets data from the http data server.
* The data is read from the ressource named filename.
* Address of new new allocated memory block is filled in pdata
* whose length is returned via plength.
*
* Returns a negative error code or a positive code from the server
*
* limitations: filename is truncated to first 256 characters
*
* Returns: HTTP error code.
**/
http_retcode http_get(const char *filename, char **pdata,
int *plength, char *typebuf);
/**
* http_parse_url:
* @url : Writable copy of an URL.
* @pfilename : Address of a pointer that will be filled with
* allocated filename. The pointer must be equal
* to NULL before calling it or it will be automatically
* freed (free(3)).
* Parses an url : setting the http_server and http_port global variables
* and returning the filename to pass to http_get/put/...
* returns a negative error code or 0 if sucessfully parsed.
*
* Returns: 0 if successfully parsed, negative error code if not.
**/
http_retcode http_parse_url(char *url, char **pfilename); http_retcode http_parse_url(char *url, char **pfilename);
/**
* http_delete:
* @filename : Name of the resource to create.
*
* Deletes data on the server
*
* Request a DELETE on the HTTP data server.
*
* Returns a negative error code or a positive code from the server
*
* limitations: filename is truncated to first 256 characters
*
* Returns: HTTP return code.
**/
http_retcode http_delete(const char *filename) ; http_retcode http_delete(const char *filename) ;
/**
* http_head:
* @filename : Name of the resource to create.
* @plength : Address of integer variable which will be set
* to length of the data.
* @typebuf : Allocated buffer where the read data
* type is returned. If NULL, the type is
* not returned.
*
* Requests the header.
*
* This function outputs the header of thehttp data server.
* The header is from the ressource named filename.
* The length and type of data is eventually returned (like for http_get(3))
*
* Returns a negative error code or a positive code from the server
*
* limitations: filename is truncated to first 256 characters
*
* Returns: HTTP return code.
**/
http_retcode http_head(const char *filename, int *plength, char *typebuf); http_retcode http_head(const char *filename, int *plength, char *typebuf);
#endif #endif