All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
QoreHttpClientObject Class Reference

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

`#include <QoreHttpClientObject.h>`

Inheritance diagram for QoreHttpClientObject:
[legend]

## Public Member Functions

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 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 AbstractQoreNode * | 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 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 QoreEncoding * | getEncoding () 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 QoreStringNode * | getProxyURL ()
| 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 QoreStringNode * | getURL ()
| returns the connection parameters as a URL, caller owns the reference count returned More...
DLLEXPORT QoreHashNode * | 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 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 AbstractQoreNode * | 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 More...
DLLEXPORT QoreHashNode * | 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 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...
Public Member Functions inherited from AbstractPrivateData
virtual DLLLOCAL void | deref ()
| decrements the reference count of the object without the possibility of throwing a Qore-language exception
DLLLOCAL void | ref ()
| increments the reference count of the object More...
Public Member Functions inherited from QoreReferenceCounter
DLLEXPORT | QoreReferenceCounter ()
| creates the reference counter object
DLLEXPORT | ~QoreReferenceCounter ()
| destroys the reference counter object
DLLLOCAL bool | is_unique () const
| returns true if the reference count is 1 More...
DLLLOCAL int | reference_count () const
| gets the reference count More...
DLLEXPORT bool | ROdereference () const
| atomically decrements the reference count More...
DLLEXPORT void | ROreference () const
| atomically increments the reference count

## Additional Inherited Members

Protected Member Functions inherited from AbstractPrivateData
virtual DLLLOCAL | ~AbstractPrivateData ()
| as these objects are reference counted, the destructor should be called only when the reference count = 0 and not manually
Protected Attributes inherited from QoreReferenceCounter
QoreThreadLock | mRO
| pthread lock to ensure atomicity of updates for architectures where we don't have an atomic increment and decrement implementation

## Detailed Description

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

thread-safe, uses QoreSocket for socket communication

## Member Function Documentation

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

adds a protocol

useful for c++ derived classes

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

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

virtual

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

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

Reimplemented from AbstractPrivateData.

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

  path | the path string to send in the header
  headers | a hash of headers to add to the message
  info | if 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)
  xsink | if 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)

DLLEXPORT const char* QoreHttpClientObject::getConnectionPath | ( |  | ) | const

returns the current connection path or 0 if none is set

Since
  Qore 0.8.8

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

DLLEXPORT const char* QoreHttpClientObject::getDefaultPath | ( |  | ) | const

returns the default path or 0 if none is set

Since
  Qore 0.8.8

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")

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

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

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

  path | the path string to send in the header
  headers | a hash of headers to add to the message
  info | if 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)
  xsink | if 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)

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

  path | the path string to send in the header
  headers | a hash of headers to add to the message
  data | optional data to send (should not be 0 for a POST)
  size | the byte length of the data to send (if this is 0 then no data is sent)
  info | if 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)
  xsink | if 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)

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

  meth | the HTTP method name to send
  path | the path string to send in the header
  headers | a hash of headers to add to the message
  data | optional data to send (may be 0)
  size | the byte length of the data to send (if this is 0 then no data is sent)
  getbody | if true then a body will be read even if there is no "Content-Length:" header
  info | if 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)
  xsink | if 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)

DLLEXPORT void QoreHttpClientObject::setConnectTimeout | ( | int | ms | ) |

sets the connect timeout in ms

Parameters

  ms | connect timeout in ms

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

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

Parameters

  header | the name of the header to send
  val | the string value to use in the HTTP header

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

sets the default path

useful for c++ derived classes

DLLEXPORT void QoreHttpClientObject::setDefaultPort | ( | int | prt | ) |

sets the default port

useful for c++ derived classes

DLLEXPORT void QoreHttpClientObject::setHTTP11 | ( | bool | h11 | ) |

sets or clears HTTP 1.1 protocol compliance

Parameters

  h11 | if true sets HTTP 1.1 protocol compliance, if false set 1.0

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

sets the http version from a string

Parameters

  version | either "1.0" or "1.1"
  xsink | if an error occurs, the Qore-language exception information will be added here

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

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

  nodelay | 0=turn off TCP_NODELAY, non-zero=turn on TCP_NODELAY

Returns
  0=OK, non-zero means an error occured, errno is set

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

    opts | the options to set for the object
    xsink | if an error occurs, the Qore-language exception information will be added here

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

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

sets the proxy URL

Parameters

  proxy | the URL to use for connection to the proxy
  xsink | if an error occurs, the Qore-language exception information will be added here

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

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

sets the username and password for the proxy connection

Parameters

  user | the username to set
  pass | the 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.

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

sets the connection URL

Parameters

  url | the URL to use for connection parameters
  xsink | if an error occurs, the Qore-language exception information will be added here

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

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

sets the username and password for the connection

Parameters

  user | the username to set
  pass | the password to set

Note
  setURL() will overwrite any settings set here

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

- include/qore/QoreHttpClientObject.h (6de6cc3b438610bf03b2bec44a3d7c61f90e3165)