neon API reference                           NEREQUESTCREATE(3)



NAME
     nerequestcreate, nerequestdispatch, nerequestdestroy -
     low-level HTP request handling

SYNOPSIS
     #include 


     nerequest *nerequestcreate (nesession *session,
                                    const char *method,
                                    const char *path);

     int nerequestdispatch (nerequest *req);

     void nerequestdestroy (nerequest *req);


DESCRIPTION
     An HTP request, represented by the nerequest type,  speci-
     fies  that  some  operation  is  to  be  performed  on  some
     resource. The nerequestcreate function creates  a  request
     object,  specifying  the  operation in the method parameter.
     The location of the resource is determined by the server  in
     use  for  the  session given by the sess parameter, combined
     with the path parameter.


     The path string used must conform to the abspath definition
     given  in  RFC2396, with an optional "?query" part, and must
     be  URI-escaped  by  the   caller   (for   instance,   using
     nepathescape).  If  the  string  comes  from  an untrusted
     source, failure to perform URI-escaping results in a securi-
     ty vulnerability.


     To  dispatch  a  request,  and  process  the  response,  the
     nerequestdispatch  function can be used. An alternative is
     to use the (more complex, but more flexible) combination  of
     the        nebeginrequest,       neendrequest,       and
     nereadresponseblock functions; see nebeginrequest.


     To  add  extra  headers  in  the  request,   the   functions
     neaddrequestheader(3)  and neprintrequestheader(3) can
     be used. To include a message body with the request, one  of
     the           functions          nesetrequestbodybuffer,
     nesetrequestbodyfd(3),  or  nesetrequestbodyprovider
     can be used.


     The return value  of  nerequestdispatch  indicates  merely
     whether  the request was sent and the response read success-



neon 0.25.5       Last change: 20 January 2006                  1






neon API reference                           NEREQUESTCREATE(3)



     fully.  To   discover   the   result   of   the   operation,
     negetstatus(3),  along with any processing of the response
     headers and message body.


     A   request   can   only   be   dispatched   once:   calling
     nerequestdispatch  more  than  once on a single nerequest
     object produces undefined behaviour. Once all processing as-
     sociated  with  the  request  object  is  complete,  use the
     nerequestdestroy function to destroy the resources associ-
     ated  with it. Any subsequent use of the request object pro-
     duces undefined behaviour.


RETURN VALUE
     The nerequestcreate function returns a pointer  to  a  re-
     quest object (and never NUL).


     The nerequestdispatch function returns zero if the request
     was  dispatched successfully, and a non-zero error code oth-
     erwise.


ERORS
     NEROR
          Request failed (see session error string)


     NELOKUP
          The DNS lookup for the server (or proxy server) failed.


     NEAUTH
          Authentication failed on the server.


     NEPROXYAUTH
          Authentication failed on the proxy server.


     NECONECT
          A connection to the server could not be established.


     NETIMEOUT
          A timeout occurred while  waiting  for  the  server  to
          respond.


EXAMPLE




neon 0.25.5       Last change: 20 January 2006                  2






neon API reference                           NEREQUESTCREATE(3)



     An example of applying a MKCOL operation to the resource  at
     the locationhttp:/www.example.com/foo/bar/:

     nesession *sess = nesessioncreate("http", "www.example.com", 80);
     nerequest *req = nerequestcreate(sess, "MKCOL", "/foo/bar/");
     if (nerequestdispatch(req)) {
        printf("Request failed: %s\n", negeterror(sess));
     }
     nerequestdestroy(req);


SEE ALSO
     negeterror(3),     neseterror(3),      negetstatus(3),
     neaddrequestheader(3), nesetrequestbodybuffer(3).


AUTHOR
     Joe Orton .

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWneon       
    
     Interface Stability  Volatile       
    

NOTES
     Source for Neon is available on http:/opensolaris.org.






















neon 0.25.5       Last change: 20 January 2006                  3