README.txt

   1
   2 ------------------------------------------------
   3 HTTP PARALLEL REQUEST & THREADING LIBRARY MODULE
   4 ------------------------------------------------
   5
   6
   7 CONTENTS OF THIS FILE
   8 ---------------------
   9
  10  * About HTTPRL
  11  * Requirements
  12  * Configuration
  13  * API Overview
  14  * Technical Details
  15  * Code Examples
  16
  17
  18 ABOUT HTTPRL
  19 ------------
  20
  21 http://drupal.org/project/httprl
  22
  23 HTTPRL is a flexible and powerful HTTP client implementation. Correctly handles
  24 GET, POST, PUT or any other HTTP requests & the sending of data. Issue blocking
  25 or non-blocking requests in parallel. Set timeouts, max simultaneous connection
  26 limits, chunk size, and max redirects to follow. Can handle data with
  27 content-encoding and transfer-encoding headers set. Correctly follows
  28 redirects. Option to forward the referrer when a redirect is found. Cookie
  29 extraction and parsing into key value pairs. Can multipart encode data so files
  30 can easily be sent in a HTTP request. Will emulate a range request if the server
  31 does not support range requests.
  32
  33
  34 REQUIREMENTS
  35 ------------
  36
  37 Requires PHP 5. The following functions must be available on the server:
  38  * stream_socket_client
  39  * stream_select
  40  * stream_set_blocking
  41  * stream_get_meta_data
  42  * stream_socket_get_name
  43 Some hosting providers disable these functions; but they do come standard with
  44 PHP 5.
  45
  46
  47 CONFIGURATION
  48 -------------
  49
  50 Settings page is located at:
  51 6.x: admin/settings/httprl
  52 7.x: admin/config/development/httprl
  53
  54  * IP Address to send all self server requests to. If left blank it will use the
  55    same server as the request. If set to -1 it will use the host name instead of
  56    an IP address. This controls the output of httprl_build_url_self().
  57  * Enable background callbacks. If disabled all background_callback keys will
  58    be turned into callback & httprl_queue_background_callback will return NULL
  59    and not queue up the request. Note that background callbacks will
  60    automatically be disabled if the site is in maintenance mode.
  61
  62
  63 API OVERVIEW
  64 ------------
  65
  66 Issue HTTP Requests:
  67 httprl_build_url_self()
  68  - Helper function to build an URL for asynchronous requests to self. Note that
  69    you should set the Host name in the headers when using this.
  70 httprl_request()
  71  - Queue up a HTTP request in httprl_send_request().
  72 httprl_send_request()
  73  - Perform many HTTP requests.
  74
  75 Create and use a thread:
  76 httprl_queue_background_callback()
  77  - Queue a special HTTP request (used for threading) in httprl_send_request().
  78
  79 Other Functions:
  80 httprl_is_background_callback_capable()
  81  - See if httprl can issue a background callback.
  82 httprl_background_processing()
  83  - Output text, close connection, continue processing in the background.
  84 httprl_strlen()
  85  - Get the length of a string in bytes.
  86 httprl_glue_url()
  87  - Alt to http_build_url().
  88 httprl_get_server_schema()
  89  - Return the server schema (http or https).
  90 httprl_pr()
  91  - Pretty print data.
  92 httprl_fast403()
  93  - Issue a 403 and exit.
  94
  95
  96 TECHNICAL DETAILS
  97 -----------------
  98
  99 Using stream_select() HTTPRL will send http requests out in parallel. These
 100 requests can be made in a blocking or non-blocking way. Blocking will wait for
 101 the http response; Non-Blocking will close the connection not waiting for the
 102 response back. The API for httprl is similar to the Drupal 7 version of
 103 drupal_http_request().
 104
 105 HTTPRL can be used independent of drupal. For basic operations it doesn't
 106 require any built in drupal functions.
 107
 108
 109 CODE EXAMPLES
 110 -------------
 111
 112 See examples/httprl.examples.php for code examples.