GrlNetWc: Grilo Reference Manual

## GrlNetWc GrlNetWc — small and simple HTTP client |

## Functions

GrlNetWc * | grl_net_wc_new ()
GQuark | grl_net_wc_error_quark ()
void | grl_net_wc_flush_delayed_requests ()
void | grl_net_wc_request_async ()
gboolean | grl_net_wc_request_finish ()
void | grl_net_wc_request_with_headers_async ()
void | grl_net_wc_request_with_headers_hash_async ()
void | grl_net_wc_set_cache ()
void | grl_net_wc_set_cache_size ()
void | grl_net_wc_set_log_level ()
void | grl_net_wc_set_throttling ()

## Types and Values

| GrlNetWc
struct | GrlNetWcClass
enum | GrlNetWcError
#define | GRL_NET_WC_ERROR

## Includes

    #include <grilo.h>

## Description

Most of the Grilo's sources need to access to web resources. The purpose of this utility class is to provide a thin and lean mechanism for those plugins to interact with those resources.

## Functions

### grl_net_wc_new ()

    GrlNetWc *
    grl_net_wc_new (void);

Creates a new GrlNetWc.

#### Returns

a new allocated instance of GrlNetWc. Do `g_object_unref()` after use it.

### grl_net_wc_error_quark ()

    GQuark
    grl_net_wc_error_quark (void);

### grl_net_wc_flush_delayed_requests ()

    void
    grl_net_wc_flush_delayed_requests (GrlNetWc *self);

This method will flush all the pending request in the queue.

#### Parameters

self | a GrlNetWc instance |

### grl_net_wc_request_async ()

    void
    grl_net_wc_request_async (GrlNetWc *self,
                              const char *uri,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Request the fetching of a web resource given the `uri` . This request is asynchronous, thus the result will be returned within the `callback` .

#### Parameters

self | a GrlNetWc instance |
uri | The URI of the resource to request |
cancellable | a GCancellable instance or `NULL` to ignore. | [allow-none]
callback | The callback when the result is ready |
user_data | User data set for the `callback` |

### grl_net_wc_request_finish ()

    gboolean
    grl_net_wc_request_finish (GrlNetWc *self,
                               GAsyncResult *result,
                               gchar **content,
                               gsize *length,
                               GError **error);

Finishes an asynchronous load of the file's contents. The contents are placed in contents, and length is set to the size of the contents string.

The content address will be invalidated at the next request. So if you want to keep it, please copy it into another address.

#### Parameters

self | a GrlNetWc instance |
result | The result of the request |
content | (out) (array length=length) (element-type guint8) (allow-none) (transfer none): The contents of the resource |
length | The length of the contents or `NULL` if it is not needed. | [out][allow-none]
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the request was successfull. If `FALSE` an error occurred.

### grl_net_wc_request_with_headers_async ()

    void
    grl_net_wc_request_with_headers_async (GrlNetWc *self,
                                           const char *uri,
                                           GCancellable *cancellable,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data,
                                           ...);

Request the fetching of a web resource given the `uri` . This request is asynchronous, thus the result will be returned within the `callback` .

#### Parameters

self | a GrlNetWc instance |
uri | The URI of the resource to request |
cancellable | a GCancellable instance or `NULL` to ignore. | [allow-none]
callback | The callback when the result is ready |
user_data | User data set for the `callback` |
... | List of tuples of header name and header value, terminated by `NULL`. |

Since: 0.2.2

### grl_net_wc_request_with_headers_hash_async ()

    void
    grl_net_wc_request_with_headers_hash_async
                                   (GrlNetWc *self,
                                    const char *uri,
                                    GHashTable *headers,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Request the fetching of a web resource given the `uri` . This request is asynchronous, thus the result will be returned within the `callback` .

[rename-to grl_net_wc_request_with_headers_async]

#### Parameters

self | a GrlNetWc instance |
uri | The URI of the resource to request |
headers | a set of additional HTTP headers for this request or `NULL` to ignore. | [allow-none][element-type utf8 utf8]
cancellable | a GCancellable instance or `NULL` to ignore. | [allow-none]
callback | The callback when the result is ready |
user_data | User data set for the `callback` |

Since: 0.2.2

### grl_net_wc_set_cache ()

    void
    grl_net_wc_set_cache (GrlNetWc *self,
                          gboolean use_cache);

Sets if cache must be used. Note that this will only work if caching is supporting. If sets `TRUE`, a new cache will be created. If sets to `FALSE`, current cache is clean and removed.

#### Parameters

self | a GrlNetWc instance |
use_cache | if cache must be used or not |

Since: 0.1.12

### grl_net_wc_set_cache_size ()

    void
    grl_net_wc_set_cache_size (GrlNetWc *self,
                               guint cache_size);

Sets the new maximum size of cache, in Megabytes. Default value is 10. Using 0 means no cache will be done.

#### Parameters

self | a GrlNetWc instance |
cache_size | size of cache (in Mb) |

Since: 0.1.12

### grl_net_wc_set_log_level ()

    void
    grl_net_wc_set_log_level (GrlNetWc *self,
                              guint log_level);

Setting the log level the logger feature is added into the libsoup session.

#### Parameters

self | a GrlNetWc instance |
log_level | the libsoup log level to set [0,3] |

### grl_net_wc_set_throttling ()

    void
    grl_net_wc_set_throttling (GrlNetWc *self,
                               guint throttling);

Setting this property, the GrlNetWc will queue all the requests and will dispatch them with a pause between them of this value.

Note that if the grl-net library was compiled against libsoup3, changing the throttling configuration will show a warning if done after the first request.

#### Parameters

self | a GrlNetWc instance |
throttling | the number of seconds to wait between requests |

## Types and Values

### GrlNetWc

    typedef struct {
      GObject parent;

      SoupSession *session;
      char *user_agent;
      SoupLoggerLogLevel log_level;
      /* throttling in secs */
      guint throttling;
      /* last request time, timestamp in seconds */
      gint64 last_request;
      /* closure queue for delayed requests */
      GQueue *pending;
      /* cache size in Mb */
      gboolean use_cache;
      guint cache_size;
      gchar *previous_data;
    } GrlNetWc;

### struct GrlNetWcClass

    struct GrlNetWcClass {
      GObjectClass parent_class;
    };

Grilo web client helper class.

It's a simple and thin web client to be used by the sources to download content from Internet.

#### Members

### enum GrlNetWcError

These constants identify all the available errors managed by the web client.

#### Members

GRL_NET_WC_ERROR_UNAVAILABLE | Deprecated. For generic errors, you should check for G_IO_ERROR_FAILED from G_IO_ERROR domain. |
GRL_NET_WC_ERROR_PROTOCOL_ERROR | Invalid URI or header |
GRL_NET_WC_ERROR_AUTHENTICATION_REQUIRED | Required authentication |
GRL_NET_WC_ERROR_NOT_FOUND | Request resource not found |
GRL_NET_WC_ERROR_CONFLICT | The entry has been modified since is was downloaded |
GRL_NET_WC_ERROR_FORBIDDEN | TBD |
GRL_NET_WC_ERROR_NETWORK_ERROR | Cannot connect to the server |
GRL_NET_WC_ERROR_PROXY_ERROR | Deprecated. You should check for G_IO_ERROR_PROXY_FAILED from G_IO_ERROR domain. |
GRL_NET_WC_ERROR_CANCELLED | Deprecated. You should check for G_IO_ERROR_CANCELLED from G_IO_ERROR domain. |

### GRL_NET_WC_ERROR

    #define GRL_NET_WC_ERROR grl_net_wc_error_quark ()