[Cosm Logo]

HTTP Protocol Functions


v3HTTPOpen

Syntax

s32 v3HTTPOpen( v3_HTTP * http, const ascii * uri,
  const u32 proxy_host, const u16 proxy_port, const ascii * proxy_name,
  const ascii * proxy_pass, const ascii * user_name,
  const ascii * user_pass );

s32 _V3_HTTPOPEN( v3_HTTP * http, const ascii * uri );

Description

Open an HTTP/1.1 (RFC 2616) connection to the given uri. The uri must be of the standard "http://host[:port][/][ignored]" form, anything past and including the single slash is ignored. proxy_host and proxy_port are the address of the web proxy, and are used if both are non-zero. The name and pass parameters are for the proxy and web page passwords.

Since v3HTTPOpen is rather complex, a macro for simpler cases is also defined. _V3_HTTPOPEN(...) allows just the first 2 parameters to be specified for when you do not need to worry about proxies or passwords.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error
V3_HTTP_ERROR_URI
URI invalid

Example





v3HTTPGet

Syntax

s32 v3HTTPGet( v3_HTTP * http, u32 * status, const ascii * uri_path,
  u32 wait_ms );

Description

Using the open http connection, open the uri_path given for reading and place the resulting HTTP status code into status. CGI parameters may be passed as part of the uri_path. This function is only used to read static web data. wait_ms is the network timeout while looking for a response to see if anything is coming back or not.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error
V3_HTTP_ERROR_NET
Host/proxy unreachable
V3_HTTP_ERROR_ORDER
Functions called in wrong order
V3_HTTP_ERROR_MEMORY
Buffer/memory error

Example





v3HTTPPost

Syntax

s32 v3HTTPPost( v3_HTTP * http, u32 * status, const ascii * uri_path,
  const void * data, u32 length, u32 wait_ms );

Description

Using the open http connection, send length bytes of data to the uri_path which is then opened for reading and the resulting HTTP status code is put into status. CGI parameter data may be sent as data, but none is allowed in the uri_path with this method. This function is primarily for communication when network traffic of blocked, but is fully compatable with web servers. wait_ms is the network timeout while looking for a response to see if anything is coming back or not.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error
V3_HTTP_ERROR_NET
Host/proxy unreachable
V3_HTTP_ERROR_ORDER
Functions called in wrong order
V3_HTTP_ERROR_MEMORY
Buffer/memory error

Example





v3HTTPRecv

Syntax

s32 v3HTTPRecv( void * buffer, u32 * bytes_received, v3_HTTP * http,
  u32 length, u32 wait_ms );

Description

Read up to length bytes of the resulting get/post data from the server into the buffer, waiting up to wait_ms milliseconds for data to arrive. bytes_read is set to the number of bytes actually read.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_ORDER
Functions called in wrong order

Example





v3HTTPClose

Syntax

s32 v3HTTPClose( v3_HTTP * http );

Description

Close the http connection and free any remaining data.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error
V3_HTTP_ERROR_NET
Host/proxy unreachable

Example





v3HTTPDInit

Syntax

s32 v3HTTPDInit( v3_HTTPD * httpd, ascii * log_path, u32 log_level,
  u32 threads, u32 stack_size, u32 ip, u16 port, u32 wait_ms );

Description

Initialize a server with threads threads, each with a stack size of stack_size, running on the ip and port given. Depending on how you write your handlers, not much stack should be needed. log_path and log_level are for the server log using a standard v3Log. wait_ms is the network timeout while parsing the request.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





v3HTTPDSetHandler

Syntax

s32 v3HTTPDSetHandler( v3_HTTPD * httpd, const ascii * path,
  v3_NET_ACL * acl, s32 (*handler)( v3_HTTPD_REQUEST * request ) );

Description

A handler will be called when a client mathching the ACL requests a URL starting with path. The handler with the longest matching path will be called, and the order handlers are added does not matter. if handler is NULL, the handler is removed. At minimum you must have a handler set for the path "/" which will be called if no other handler matches.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





v3HTTPDStart

Syntax

s32 v3HTTPDStart( v3_HTTPD * httpd, u32 timeout_ms );

Description

Starts the httpd server once it is initialized and handlers are set.

Since your server will probably be stopped by a message or signal, the correct way to see that it is still running is to check that httpd.status != V3_HTTPD_STATUS_STOPPED.

It is possible on some systems for severe network driver errors to stop the server. Calling v3HTTPStart again may be able to restart it.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error
V3_HTTPD_ERROR_TIMOUT
Unable to start the server.

Example




v3HTTPDStop

Syntax

s32 v3HTTPDStop( v3_HTTPD * httpd, u32 timeout_ms );

Description

Stops the httpd server, possibly to change the handlers. If the threads cannot be shutdown within timout_ms milliseconds, then V3_HTTPD_ERROR_TIMOUT is returned and you can attempt to stop it again.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





v3HTTPDSendInit

Syntax

s32 v3HTTPDSendInit( v3_HTTPD_REQUEST * request, ascii * code,
  ascii * string, ascii * type );

Description

This is the first function that should be called in any handler. code is the 3 digit HTTP status ("200", "404") for the result. string is the text associated with the that code ("OK", "Not Found"). type is the media type of data to be sent, "text/http" for tunneling purposes, or a type based on the content like "image/jpeg". Further information on these parameters can be found in the HTTP/1.1 documentation (RFC 2616).

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





v3HTTPDSendHead

Syntax

s32 v3HTTPDSendHead( v3_HTTPD_REQUEST * request, const void * string );

Description

Send the string to the client as part of the HTTP header sent in handler functions. This function must be used after v3HTTPDSendInit but before any v3HTTPDSend are called.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





v3HTTPDSend

Syntax

s32 v3HTTPDSend( v3_HTTPD_REQUEST * request, const void * data, u32 length );

Description

Send length bytes of data to the client in a handler function.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





v3HTTPDRecv

Syntax

s32 v3HTTPDRecv( void * buffer, u32 * bytes_received,
  v3_HTTPD_REQUEST * request, u32 length, u32 wait_ms );

Description

Read up to length bytes of the posted data from the client into the buffer, waiting up to wait_ms milliseconds for data to arrive. bytes_received is set to the number of bytes actually read. For use in handler functions.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





v3HTTPDFree

Syntax

s32 v3HTTPDFree( v3_HTTPD * httpd );

Description

Free the httpd and any remaining data. A server must not be running in order to free it.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_HTTP_ERROR_PARAM
Parameter error

Example





© Copyright Mithral Communications & Design Inc. 1995-2003. All rights reserved. Mithral® and Cosm® are trademarks of Mithral Communications & Design Inc.
Document last modified: May 22, 2003