[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-2024.
    All rights reserved.
    Mithral® and Cosm® are trademarks of
    Mithral Communications & Design Inc.
    

    
    Document last modified: Jun 01, 2012