GrlNetWc

GrlNetWc — small and simple HTTP client

Synopsis

#include <grilo.h>

struct              GrlNetWc;
struct              GrlNetWcClass;
enum                GrlNetWcError;
#define             GRL_NET_WC_ERROR
GrlNetWc *          grl_net_wc_new                      (void);
GQuark              grl_net_wc_error_quark              (void);
void                grl_net_wc_flush_delayed_requests   (GrlNetWc *self);
void                grl_net_wc_request_async            (GrlNetWc *self,
                                                         const char *uri,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            grl_net_wc_request_finish           (GrlNetWc *self,
                                                         GAsyncResult *result,
                                                         gchar **content,
                                                         gsize *length,
                                                         GError **error);
void                grl_net_wc_request_with_headers_async
                                                        (GrlNetWc *self,
                                                         const char *uri,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data,
                                                         ...);
void                grl_net_wc_request_with_headers_hash_async
                                                        (GrlNetWc *self,
                                                         const char *uri,
                                                         GHashTable *headers,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
void                grl_net_wc_set_cache                (GrlNetWc *self,
                                                         gboolean use_cache);
void                grl_net_wc_set_cache_size           (GrlNetWc *self,
                                                         guint cache_size);
void                grl_net_wc_set_log_level            (GrlNetWc *self,
                                                         guint log_level);
void                grl_net_wc_set_throttling           (GrlNetWc *self,
                                                         guint throttling);

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.

Details

struct GrlNetWc

struct GrlNetWc {
  GObject parent;
};

GObject parent;

the parent object struct

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.

GObjectClass parent_class;

the parent class structure

enum GrlNetWcError

typedef enum {
	GRL_NET_WC_ERROR_UNAVAILABLE = 1,
	GRL_NET_WC_ERROR_PROTOCOL_ERROR,
	GRL_NET_WC_ERROR_AUTHENTICATION_REQUIRED,
	GRL_NET_WC_ERROR_NOT_FOUND,
	GRL_NET_WC_ERROR_CONFLICT,
	GRL_NET_WC_ERROR_FORBIDDEN,
	GRL_NET_WC_ERROR_NETWORK_ERROR,
	GRL_NET_WC_ERROR_PROXY_ERROR,
	GRL_NET_WC_ERROR_CANCELLED
} GrlNetWcError;

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

GRL_NET_WC_ERROR_UNAVAILABLE

TBD

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

Cannot connect to the proxy server

GRL_NET_WC_ERROR_CANCELLED

The operation has been cancelled (see GCancellable)

GRL_NET_WC_ERROR

#define GRL_NET_WC_ERROR grl_net_wc_error_quark ()

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.

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.

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.

self :

a GrlNetWc instance

result :

The result of the request

content :

The contents of the resource

length :

The length of the contents or NULL if it is not needed. [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.

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

Varargs :

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.

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.

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.

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.

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.

self :

a GrlNetWc instance

throttling :

the number of seconds to wait between requests