[Cosm Logo]

HTTP Protocol Functions


CosmHTTPOpen

Syntax

s32 CosmHTTPOpen( cosm_HTTP * http, const ascii * uri,
  const cosm_NET_ADDR proxy_host, const u16 proxy_port, const ascii * proxy_name,
  const ascii * proxy_pass, const ascii * user_name,
  const ascii * user_pass );

s32 _COSM_HTTPOPEN( cosm_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 CosmHTTPOpen is rather complex, a macro for simpler cases is also defined. _COSM_HTTPOPEN(...) allows just the first 2 parameters to be specified for when you do not need to worry about proxies or passwords.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error
COSM_HTTP_ERROR_URI
URI invalid

Example





CosmHTTPGet

Syntax

s32 CosmHTTPGet( cosm_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error
COSM_HTTP_ERROR_NET
Host/proxy unreachable
COSM_HTTP_ERROR_ORDER
Functions called in wrong order
COSM_HTTP_ERROR_MEMORY
Buffer/memory error

Example





CosmHTTPPost

Syntax

s32 CosmHTTPPost( cosm_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error
COSM_HTTP_ERROR_NET
Host/proxy unreachable
COSM_HTTP_ERROR_ORDER
Functions called in wrong order
COSM_HTTP_ERROR_MEMORY
Buffer/memory error

Example





CosmHTTPRecv

Syntax

s32 CosmHTTPRecv( void * buffer, u32 * bytes_received, cosm_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_ORDER
Functions called in wrong order

Example





CosmHTTPClose

Syntax

s32 CosmHTTPClose( cosm_HTTP * http );

Description

Close the http connection and free any remaining data.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error
COSM_HTTP_ERROR_NET
Host/proxy unreachable

Example





CosmHTTPDInit

Syntax

s32 CosmHTTPDInit( cosm_HTTPD * httpd, ascii * log_path, u32 log_level,
  u32 threads, u32 stack_size, cosm_NET_ADDR 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 CosmLog. wait_ms is the network timeout while parsing the request.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





CosmHTTPDSetHandler

Syntax

s32 CosmHTTPDSetHandler( cosm_HTTPD * httpd, const ascii * path,
  cosm_NET_ACL * acl, s32 (*handler)( cosm_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





CosmHTTPDStart

Syntax

s32 CosmHTTPDStart( cosm_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 != COSM_HTTPD_STATUS_STOPPED.

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTPD_ERROR_PARAM
Parameter error
COSM_HTTPD_ERROR_TIMEOUT
Unable to start the server.

Example




CosmHTTPDStop

Syntax

s32 CosmHTTPDStop( cosm_HTTPD * httpd, u32 timeout_ms );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





CosmHTTPDSendInit

Syntax

s32 CosmHTTPDSendInit( cosm_HTTPD_REQUEST * request, u32 status_code,
  ascii * status_string, ascii * mime_type );

Description

This is the first function that should be called in any handler. status_code is the 3 digit HTTP status code. status_string is the text associated with the that code, for 200 it is "OK". mime_type is the media type of data to be sent based on the content. Further information on these parameters can be found in the HTTP/1.1 documentation (RFC 2616).

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





CosmHTTPDSendHead

Syntax

s32 CosmHTTPDSendHead( cosm_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 CosmHTTPDSendInit but before any CosmHTTPDSend are called.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





CosmHTTPDSend

Syntax

s32 CosmHTTPDSend( cosm_HTTPD_REQUEST * request, const void * data, u32 length );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





CosmHTTPDRecv

Syntax

s32 CosmHTTPDRecv( void * buffer, u32 * bytes_received,
  cosm_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





CosmHTTPDFree

Syntax

s32 CosmHTTPDFree( cosm_HTTPD * httpd );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_HTTP_ERROR_PARAM
Parameter error

Example





© Copyright Mithral Communications & Design Inc. 1995-2017. All rights reserved. Mithral® and Cosm® are trademarks of Mithral Communications & Design Inc.
Document last modified: Jun 01, 2012