doc/nd/Overviews/Overview_Network.txt

   1 Title: Overview: Network
   2
   3 About: Network Interface
   4
   5 Allows overriding the default use of <libcurl at http://curl.haxx.se/libcurl/c/>
   6 in libquvi. For example, an application could use <libsoup at
   7 http://live.gnome.org/LibSoup> instead of libcurl.
   8
   9 About: Requirements
  10
  11 An application must set the necessary properties in its corresponding
  12 callbacks. Besides the <Common properties>, each callback is expected to
  13 set any additional properties listed below.
  14
  15 About: Common properties
  16
  17 (start code)
  18 quvi_net_setprop(net_handle, QUVI_NET_PROPERTY_RESPONSECODE, resp_code);
  19 (end)
  20
  21 Common properties that are expected to be set by all callbacks.
  22
  23   * <QUVI_NET_PROPERTY_RESPONSECODE>
  24
  25 About: quvi_callback_fetch
  26
  27 (start code)
  28 quvi_setopt(session_handle, QUVIOPT_FETCHFUNCTION, &fetch_callback_func);
  29 (end)
  30
  31 In addition to the <Common properties>, must set
  32   * <QUVI_NET_PROPERTY_CONTENT>
  33
  34 Return:
  35   * Either <QUVI_OK> or <QUVI_CALLBACK> if an error occurred
  36
  37 About: quvi_callback_resolve
  38
  39 (start code)
  40 quvi_setopt(session_handle, QUVIOPT_RESOLVEFUNCTION, &resolve_callback_func);
  41 (end)
  42
  43 In addition to the <Common properties> -- *if* a redirection to another
  44 location was found, *then* must set
  45   * <QUVI_NET_PROPERTY_REDIRECTURL>
  46
  47 Notes:
  48
  49 This callback should return <QUVI_CALLBACK> *only* if an
  50 unrecoverable error occurred, e.g. a network error. Return <QUVI_OK> in
  51 all other cases, including those in which a redirection URL was not
  52 found.
  53
  54 Return:
  55   * Either <QUVI_OK> or <QUVI_CALLBACK> if an (e.g. network) error occurred
  56   * Return <QUVI_OK> even if a redirection URL was not found
  57
  58 About: quvi_callback_verify
  59
  60 (start code)
  61 quvi_setopt(session_handle, QUVIOPT_VERIFYFUNCTION, &verify_callback_func);
  62 (end)
  63
  64 In addition to the <Common properties>, must set
  65   * <QUVI_NET_PROPERTY_CONTENTTYPE>
  66   * <QUVI_NET_PROPERTY_CONTENTLENGTH>
  67
  68 Return:
  69   * Either <QUVI_OK> or <QUVI_CALLBACK> if an error occurred
  70
  71 About: Example
  72
  73 Basic example. This example assumes that a fictional `do_fetch' function
  74 fetches the data over the network. The callback then relays the data
  75 and any errors back to libquvi. Some error checks omitted for brewity.
  76
  77 (start code)
  78 static QUVIcode fetch_callback(quvi_net_t net_handle)
  79 {
  80   char *url, *reason, *content;
  81   long resp_code;
  82   int fetch_ok;
  83
  84   quvi_net_getprop(net_handle, QUVI_NET_PROPERTY_URL, &url);
  85
  86   fetch_ok = do_fetch(url, &content, &resp_code, &reason);
  87
  88   quvi_net_setprop(net_handle, QUVI_NET_PROPERTY_RESPONSECODE, resp_code);
  89
  90   if (fetch_ok)
  91     {
  92       quvi_net_setprop(net_handle, QUVI_NET_PROPERTY_CONTENT, content);
  93       return (QUVI_OK);
  94     }
  95
  96   quvi_net_seterr(net_handle, "%s (http/%d)", reason, resp_code);
  97
  98   return (QUVI_CALLBACK); /* Tell the library an error occurred */
  99 }
 100
 101 int main(int argc, char **argv)
 102 {
 103   quvi_t q;
 104   quvi_init(&q);
 105   quvi_setopt(q, QUVIOPT_FETCHFUNCTION, &fetch_callback);
 106   quvi_parse(...);
 107   quvi_close(&q);
 108   return (0);
 109 }
 110 (end)