Qore Programming Language  0.9.0
QoreHttpClientObject Class Reference

provides a way to communicate with HTTP servers using Qore data structures More...

#include <QoreHttpClientObject.h>

Inheritance diagram for QoreHttpClientObject:

Public Member Methods

DLLEXPORT QoreHttpClientObject ()
 creates the QoreHttpClientObject object
 
virtual DLLEXPORT ~QoreHttpClientObject ()
 destroys the object and frees all associated memory
 
DLLEXPORT void addProtocol (const char *prot, int port, bool ssl=false)
 adds a protocol More...
 
DLLEXPORT void clearProxyURL ()
 clears the proxy URL
 
DLLEXPORT void clearProxyUserPassword ()
 clears the username and password for the proxy connection
 
DLLEXPORT void clearUserPassword ()
 clears the username and password for the connection
 
DLLEXPORT int connect (ExceptionSink *xsink)
 opens a connection and returns a code giving the result More...
 
virtual DLLLOCAL void deref (ExceptionSink *xsink)
 decrements the reference count of the object More...
 
virtual DLLLOCAL void deref ()
 decrements the reference count of the object without the possibility of throwing a Qore-language exception
 
virtual DLLEXPORT void deref (ExceptionSink *xsink)
 decrements the reference count and deletes the object when it reaches 0 More...
 
DLLEXPORT void disconnect ()
 disconnects from the remote server
 
DLLEXPORT AbstractQoreNodeget (const char *path, const QoreHashNode *headers, QoreHashNode *info, ExceptionSink *xsink)
 sends an HTTP "GET" method and returns the value of the message body returned, the caller owns the AbstractQoreNode reference returned More...
 
DLLEXPORT const char * getConnectionPath () const
 returns the current connection path or 0 if none is set More...
 
DLLEXPORT int getConnectTimeout () const
 returns the connect timeout in ms, negative numbers mean no timeout More...
 
DLLEXPORT const char * getDefaultPath () const
 returns the default path or 0 if none is set More...
 
DLLEXPORT const QoreEncodinggetEncoding () const
 returns the default encoding for the object
 
DLLEXPORT const char * getHTTPVersion () const
 returns the http version as a string (either "1.0" or "1.1") More...
 
DLLEXPORT int getMaxRedirects () const
 returns the value of the max_redirects option
 
DLLEXPORT bool getNoDelay () const
 returns the value of the TCP_NODELAY flag on the object
 
DLLEXPORT QoreStringNodegetProxyURL ()
 returns the proxy connection parameters as a URL (or 0 if there is none), caller owns the reference count returned More...
 
DLLEXPORT int getTimeout () const
 returns the connection and response packet timeout value in milliseconds
 
DLLEXPORT QoreStringNodegetURL ()
 returns the connection parameters as a URL, caller owns the reference count returned More...
 
DLLEXPORT QoreHashNodehead (const char *path, const QoreHashNode *headers, QoreHashNode *info, ExceptionSink *xsink)
 sends an HTTP "HEAD" method and returns the headers returned, the caller owns the QoreHashNode reference returned More...
 
DLLEXPORT bool isConnected () const
 returns the connection status of the object
 
DLLEXPORT bool isHTTP11 () const
 returns true if HTTP 1.1 protocol compliance has been set
 
DLLEXPORT bool isProxySecure () const
 returns the SSL proxy connection parameter flag
 
DLLEXPORT bool isSecure () const
 returns the SSL connection parameter flag
 
DLLEXPORT AbstractQoreNodepost (const char *path, const QoreHashNode *headers, const void *data, unsigned size, QoreHashNode *info, ExceptionSink *xsink)
 sends an HTTP "POST" message to the remote server and returns the message body of the response, caller owns the AbstractQoreNode reference returned More...
 
DLLEXPORT QoreHashNodesend (const char *meth, const char *path, const QoreHashNode *headers, const void *data, unsigned size, bool getbody, QoreHashNode *info, ExceptionSink *xsink)
 sends a message to the remote server and returns the entire response as a hash, caller owns the QoreHashNode reference returned More...
 
DLLEXPORT void sendChunked (const char *meth, const char *mpath, const QoreHashNode *headers, bool getbody, QoreHashNode *info, int timeout_ms, const ResolvedCallReferenceNode *recv_callback, QoreObject *obj, OutputStream *os, InputStream *is, size_t max_chunk_size, const ResolvedCallReferenceNode *trailer_callback, ExceptionSink *xsink)
 send a chunked HTTP message through an InputStream and receive the response to an OutputStream More...
 
DLLEXPORT void sendWithOutputStream (const char *meth, const char *mpath, const QoreHashNode *headers, const void *data, unsigned size, bool getbody, QoreHashNode *info, int timeout_ms, const ResolvedCallReferenceNode *recv_callback, QoreObject *obj, OutputStream *os, ExceptionSink *xsink)
 make an HTTP request and receive the response to an OutputStream More...
 
DLLEXPORT void setConnectTimeout (int ms)
 sets the connect timeout in ms More...
 
DLLEXPORT void setDefaultHeaderValue (const char *header, const char *val)
 sets the value of a default header to send with every outgoing message More...
 
DLLEXPORT void setDefaultPath (const char *pth)
 sets the default path More...
 
DLLEXPORT void setDefaultPort (int prt)
 sets the default port More...
 
DLLEXPORT void setEncoding (const QoreEncoding *qe)
 sets the default encoding for the object
 
DLLEXPORT void setEventQueue (Queue *cbq, ExceptionSink *xsink)
 sets the event queue, must be already referenced before call
 
DLLEXPORT void setHTTP11 (bool h11)
 sets or clears HTTP 1.1 protocol compliance More...
 
DLLEXPORT int setHTTPVersion (const char *version, ExceptionSink *xsink)
 sets the http version from a string More...
 
DLLEXPORT void setMaxRedirects (int max)
 sets the max_redirects option
 
DLLEXPORT int setNoDelay (bool nodelay)
 sets the TCP_NODELAY flag on the object More...
 
DLLEXPORT int setOptions (const QoreHashNode *opts, ExceptionSink *xsink)
 set options with a hash, returns -1 if an exception was thrown, 0 for OK More...
 
DLLEXPORT void setPersistent (ExceptionSink *xsink)
 temporarily disables implicit reconnections; must be called when the server is already connected
 
DLLEXPORT void setProxySecure (bool is_secure)
 sets the SSL flag for use in the next connection to the proxy
 
DLLEXPORT int setProxyURL (const char *proxy, ExceptionSink *xsink)
 sets the proxy URL More...
 
DLLEXPORT void setProxyUserPassword (const char *user, const char *pass)
 sets the username and password for the proxy connection More...
 
DLLEXPORT void setSecure (bool is_secure)
 sets the SSL flag for use in the next connection
 
DLLEXPORT void setTimeout (int to)
 sets the connection and response packet timeout value in milliseconds
 
DLLEXPORT int setURL (const char *url, ExceptionSink *xsink)
 sets the connection URL More...
 
DLLEXPORT void setUserPassword (const char *user, const char *pass)
 sets the username and password for the connection More...
 

Detailed Description

provides a way to communicate with HTTP servers using Qore data structures

thread-safe, uses QoreSocket for socket communication

Member Function Documentation

◆ addProtocol()

DLLEXPORT void QoreHttpClientObject::addProtocol ( const char *  prot,
int  port,
bool  ssl = false 
)

adds a protocol

useful for c++ derived classes

◆ connect()

DLLEXPORT int QoreHttpClientObject::connect ( ExceptionSink xsink)

opens a connection and returns a code giving the result

Returns
-1 if an exception was thrown, 0 for OK

◆ deref() [1/2]

virtual DLLLOCAL void AbstractPrivateData::deref
inline

decrements the reference count of the object

Parameters
xsinkany Qore-language exception information is stored here

◆ deref() [2/2]

virtual DLLEXPORT void QoreHttpClientObject::deref ( ExceptionSink xsink)
virtual

decrements the reference count and deletes the object when it reaches 0

Parameters
xsinkif an error occurs, the Qore-language exception information will be added here

Reimplemented from AbstractPrivateData.

◆ get()

DLLEXPORT AbstractQoreNode* QoreHttpClientObject::get ( const char *  path,
const QoreHashNode headers,
QoreHashNode info,
ExceptionSink xsink 
)

sends an HTTP "GET" method and returns the value of the message body returned, the caller owns the AbstractQoreNode reference returned

if you need to get all the headers received, then use QoreHttpClientObject::send() instead

Parameters
paththe path string to send in the header
headersa hash of headers to add to the message
infoif not 0 then additional information about the HTTP communication will be added to the hash (key-value pairs), keys "headers", and optionally "redirect-#", "redirect-message-#" (where # is substituted with the redirect sequence number), and "chunked" (boolean, present only if the response was chunked)
xsinkif an error occurs, the Qore-language exception information will be added here
Returns
the body of the response message, caller owns the QoreHashNode reference returned (0 if there was an error or no body returned)

◆ getConnectionPath()

DLLEXPORT const char* QoreHttpClientObject::getConnectionPath ( ) const

returns the current connection path or 0 if none is set

Since
Qore 0.8.8

◆ getConnectTimeout()

DLLEXPORT int QoreHttpClientObject::getConnectTimeout ( ) const

returns the connect timeout in ms, negative numbers mean no timeout

Returns
the connect timeout in ms, negative numbers mean no timeout

◆ getDefaultPath()

DLLEXPORT const char* QoreHttpClientObject::getDefaultPath ( ) const

returns the default path or 0 if none is set

Since
Qore 0.8.8

◆ getHTTPVersion()

DLLEXPORT const char* QoreHttpClientObject::getHTTPVersion ( ) const

returns the http version as a string (either "1.0" or "1.1")

Returns
the http version as a string (either "1.0" or "1.1")

◆ getProxyURL()

DLLEXPORT QoreStringNode* QoreHttpClientObject::getProxyURL ( )

returns the proxy connection parameters as a URL (or 0 if there is none), caller owns the reference count returned

Returns
the proxy connection parameters as a URL, caller owns the reference count returned

◆ getURL()

DLLEXPORT QoreStringNode* QoreHttpClientObject::getURL ( )

returns the connection parameters as a URL, caller owns the reference count returned

Returns
the connection parameters as a URL, caller owns the reference count returned

◆ head()

DLLEXPORT QoreHashNode* QoreHttpClientObject::head ( const char *  path,
const QoreHashNode headers,
QoreHashNode info,
ExceptionSink xsink 
)

sends an HTTP "HEAD" method and returns the headers returned, the caller owns the QoreHashNode reference returned

Parameters
paththe path string to send in the header
headersa hash of headers to add to the message
infoif not 0 then additional information about the HTTP communication will be added to the hash (key-value pairs), keys "headers", and optionally "redirect-#", "redirect-message-#" (where # is substituted with the redirect sequence number), and "chunked" (boolean, present only if the response was chunked)
xsinkif an error occurs, the Qore-language exception information will be added here
Returns
the entire response as a hash, caller owns the QoreHashNode reference returned (0 if there was an error)

◆ post()

DLLEXPORT AbstractQoreNode* QoreHttpClientObject::post ( const char *  path,
const QoreHashNode headers,
const void *  data,
unsigned  size,
QoreHashNode info,
ExceptionSink xsink 
)

sends an HTTP "POST" message to the remote server and returns the message body of the response, caller owns the AbstractQoreNode reference returned

possible errors: method not recognized, redirection errors, socket communication errors, timeout errors

Parameters
paththe path string to send in the header
headersa hash of headers to add to the message
dataoptional data to send (should not be 0 for a POST)
sizethe byte length of the data to send (if this is 0 then no data is sent)
infoif not 0 then additional information about the HTTP communication will be added to the hash (key-value pairs), keys "headers", and optionally "redirect-#", "redirect-message-#" (where # is substituted with the redirect sequence number), and "chunked" (boolean, present only if the response was chunked)
xsinkif an error occurs, the Qore-language exception information will be added here
Returns
the body of the response message, caller owns the QoreHashNode reference returned (0 if there was an error or no body returned)

◆ send()

DLLEXPORT QoreHashNode* QoreHttpClientObject::send ( const char *  meth,
const char *  path,
const QoreHashNode headers,
const void *  data,
unsigned  size,
bool  getbody,
QoreHashNode info,
ExceptionSink xsink 
)

sends a message to the remote server and returns the entire response as a hash, caller owns the QoreHashNode reference returned

possible errors: method not recognized, redirection errors, socket communication errors, timeout errors

Parameters
meththe HTTP method name to send
paththe path string to send in the header
headersa hash of headers to add to the message
dataoptional data to send (may be 0)
sizethe byte length of the data to send (if this is 0 then no data is sent)
getbodyif true then a body will be read even if there is no "Content-Length:" header
infoif not 0 then additional information about the HTTP communication will be added to the hash (key-value pairs), keys "headers", and optionally "redirect-#", "redirect-message-#" (where # is substituted with the redirect sequence number), and "chunked" (boolean, present only if the response was chunked)
xsinkif an error occurs, the Qore-language exception information will be added here
Returns
the entire response as a hash, caller owns the QoreHashNode reference returned (0 if there was an error)

◆ sendChunked()

DLLEXPORT void QoreHttpClientObject::sendChunked ( const char *  meth,
const char *  mpath,
const QoreHashNode headers,
bool  getbody,
QoreHashNode info,
int  timeout_ms,
const ResolvedCallReferenceNode recv_callback,
QoreObject obj,
OutputStream os,
InputStream is,
size_t  max_chunk_size,
const ResolvedCallReferenceNode trailer_callback,
ExceptionSink xsink 
)

send a chunked HTTP message through an InputStream and receive the response to an OutputStream

Since
Qore 0.8.13

◆ sendWithOutputStream()

DLLEXPORT void QoreHttpClientObject::sendWithOutputStream ( const char *  meth,
const char *  mpath,
const QoreHashNode headers,
const void *  data,
unsigned  size,
bool  getbody,
QoreHashNode info,
int  timeout_ms,
const ResolvedCallReferenceNode recv_callback,
QoreObject obj,
OutputStream os,
ExceptionSink xsink 
)

make an HTTP request and receive the response to an OutputStream

Since
Qore 0.8.13

◆ setConnectTimeout()

DLLEXPORT void QoreHttpClientObject::setConnectTimeout ( int  ms)

sets the connect timeout in ms

Parameters
msconnect timeout in ms

◆ setDefaultHeaderValue()

DLLEXPORT void QoreHttpClientObject::setDefaultHeaderValue ( const char *  header,
const char *  val 
)

sets the value of a default header to send with every outgoing message

Parameters
headerthe name of the header to send
valthe string value to use in the HTTP header

◆ setDefaultPath()

DLLEXPORT void QoreHttpClientObject::setDefaultPath ( const char *  pth)

sets the default path

useful for c++ derived classes

◆ setDefaultPort()

DLLEXPORT void QoreHttpClientObject::setDefaultPort ( int  prt)

sets the default port

useful for c++ derived classes

◆ setHTTP11()

DLLEXPORT void QoreHttpClientObject::setHTTP11 ( bool  h11)

sets or clears HTTP 1.1 protocol compliance

Parameters
h11if true sets HTTP 1.1 protocol compliance, if false set 1.0

◆ setHTTPVersion()

DLLEXPORT int QoreHttpClientObject::setHTTPVersion ( const char *  version,
ExceptionSink xsink 
)

sets the http version from a string

Parameters
versioneither "1.0" or "1.1"
xsinkif an error occurs, the Qore-language exception information will be added here
Returns
-1 if an exception was thrown, 0 for OK

◆ setNoDelay()

DLLEXPORT int QoreHttpClientObject::setNoDelay ( bool  nodelay)

sets the TCP_NODELAY flag on the object

This function will try to set the TCP_NODELAY flag immediately if the socket is connected, otherwise will it set a flag and the TCP_NODELAY option will be set on the next connection. If an error occurs setting TCP_NODELAY on a connected socket, then this function will return a non-zero value, and errno will be set

Parameters
nodelay0=turn off TCP_NODELAY, non-zero=turn on TCP_NODELAY
Returns
0=OK, non-zero means an error occured, errno is set

◆ setOptions()

DLLEXPORT int QoreHttpClientObject::setOptions ( const QoreHashNode opts,
ExceptionSink xsink 
)

set options with a hash, returns -1 if an exception was thrown, 0 for OK

options are:

  • protocols: a hash where each key is a protocol name and the value must be set to a integer giving a port number or a hash having the following keys:
  • port: giving the port number
  • ssl: giving a boolean true or false value
  • max_redirects: sets the max_redirects option
  • default_port: sets the default port number
  • proxy: sets the proxy URL
  • url: sets the default connection URL
  • default_path: sets the default path
  • timeout: sets the connection or response packet timeout value in milliseconds
  • http_version: either "1.0" or "1.1" to set the default HTTP version to use
  • connect_timeout: an integer giving the timeout value for new socket connections in milliseconds
    Note
    this function is unlocked and designed only to be called with the constructor
    Parameters
    optsthe options to set for the object
    xsinkif an error occurs, the Qore-language exception information will be added here
    Returns
    -1 if an exception was thrown, 0 for OK

◆ setProxyURL()

DLLEXPORT int QoreHttpClientObject::setProxyURL ( const char *  proxy,
ExceptionSink xsink 
)

sets the proxy URL

Parameters
proxythe URL to use for connection to the proxy
xsinkif an error occurs, the Qore-language exception information will be added here
Returns
-1 if an exception was thrown, 0 for OK

◆ setProxyUserPassword()

DLLEXPORT void QoreHttpClientObject::setProxyUserPassword ( const char *  user,
const char *  pass 
)

sets the username and password for the proxy connection

Parameters
userthe username to set
passthe password to set
Note
these settings will only take effect if a proxy URL is set, so it only makes sense to call this function after setProxyURL(); also setProxyURL() will overwrite any settings here.

◆ setURL()

DLLEXPORT int QoreHttpClientObject::setURL ( const char *  url,
ExceptionSink xsink 
)

sets the connection URL

Parameters
urlthe URL to use for connection parameters
xsinkif an error occurs, the Qore-language exception information will be added here
Returns
-1 if an exception was thrown, 0 for OK

◆ setUserPassword()

DLLEXPORT void QoreHttpClientObject::setUserPassword ( const char *  user,
const char *  pass 
)

sets the username and password for the connection

Parameters
userthe username to set
passthe password to set
Note
setURL() will overwrite any settings set here

The documentation for this class was generated from the following file: