[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