GrssFeedChannel: libgrss Reference Manual

## GrssFeedChannel GrssFeedChannel — a feed |

## Functions

#define | FEED_CHANNEL_CLASS()
GrssFeedChannel * | grss_feed_channel_new ()
GrssFeedChannel * | grss_feed_channel_new_with_source ()
GrssFeedChannel * | grss_feed_channel_new_from_xml ()
GrssFeedChannel * | grss_feed_channel_new_from_memory ()
GrssFeedChannel * | grss_feed_channel_new_from_file ()
void | grss_feed_channel_set_format ()
const gchar * | grss_feed_channel_get_format ()
gboolean | grss_feed_channel_set_source ()
const gchar * | grss_feed_channel_get_source ()
void | grss_feed_channel_set_title ()
const gchar * | grss_feed_channel_get_title ()
gboolean | grss_feed_channel_set_homepage ()
const gchar * | grss_feed_channel_get_homepage ()
void | grss_feed_channel_set_description ()
const gchar * | grss_feed_channel_get_description ()
gboolean | grss_feed_channel_set_image ()
const gchar * | grss_feed_channel_get_image ()
gboolean | grss_feed_channel_set_icon ()
const gchar * | grss_feed_channel_get_icon ()
void | grss_feed_channel_set_language ()
const gchar * | grss_feed_channel_get_language ()
void | grss_feed_channel_set_category ()
const gchar * | grss_feed_channel_get_category ()
gboolean | grss_feed_channel_set_pubsubhub ()
gboolean | grss_feed_channel_get_pubsubhub ()
void | grss_feed_channel_set_rsscloud ()
gboolean | grss_feed_channel_get_rsscloud ()
void | grss_feed_channel_set_copyright ()
const gchar * | grss_feed_channel_get_copyright ()
void | grss_feed_channel_set_editor ()
GrssPerson * | grss_feed_channel_get_editor ()
void | grss_feed_channel_add_contributor ()
const GList * | grss_feed_channel_get_contributors ()
void | grss_feed_channel_add_cookie ()
GSList * | grss_feed_channel_get_cookies ()
void | grss_feed_channel_set_webmaster ()
const gchar * | grss_feed_channel_get_webmaster ()
void | grss_feed_channel_set_generator ()
const gchar * | grss_feed_channel_get_generator ()
void | grss_feed_channel_set_gzip_compression ()
gboolean | grss_feed_channel_get_gzip_compression ()
void | grss_feed_channel_set_publish_time ()
time_t | grss_feed_channel_get_publish_time ()
void | grss_feed_channel_set_update_time ()
time_t | grss_feed_channel_get_update_time ()
void | grss_feed_channel_set_update_interval ()
int | grss_feed_channel_get_update_interval ()
gboolean | grss_feed_channel_fetch ()
void | grss_feed_channel_fetch_async ()
gboolean | grss_feed_channel_fetch_finish ()
GList * | grss_feed_channel_fetch_all ()
void | grss_feed_channel_fetch_all_async ()
GList * | grss_feed_channel_fetch_all_finish ()
gboolean | grss_feed_channel_fetch_cancel ()

## Types and Values

#define | GRSS_FEED_CHANNEL_TYPE

## Object Hierarchy

        GObject
        ╰── GrssFeedChannel

## Description

GrssFeedChannel rappresents a single feed which may be fetched and parsed.

## Functions

### FEED_CHANNEL_CLASS()

    #define FEED_CHANNEL_CLASS(c)		(G_TYPE_CHECK_CLASS_CAST ((c), GRSS_FEED_CHANNEL_TYPE, GrssFeedChannelClass))

### grss_feed_channel_new ()

    GrssFeedChannel *
    grss_feed_channel_new ();

Allocates a new GrssFeedChannel.

#### Returns

a GrssFeedChannel.

### grss_feed_channel_new_with_source ()

    GrssFeedChannel *
    grss_feed_channel_new_with_source (gchar *source);

Allocates a new GrssFeedChannel and assign it the given remote source.

#### Parameters

source | URL of the feed. |

#### Returns

a GrssFeedChannel.

### grss_feed_channel_new_from_xml ()

    GrssFeedChannel *
    grss_feed_channel_new_from_xml (xmlDocPtr doc,
                                    GError **error);

Allocates a new GrssFeedChannel and init it with contents found in specified XML document.

#### Parameters

doc | an XML document previously parsed with libxml2. |
error | if an error occurred, `NULL` is returned and this is filled with the message. |

#### Returns

a GrssFeedChannel, or `NULL` if an error occurs.

### grss_feed_channel_new_from_memory ()

    GrssFeedChannel *
    grss_feed_channel_new_from_memory (const gchar *data,
                                       GError **error);

Allocates a new GrssFeedChannel and init it with contents found in specified memory block.

#### Parameters

data | string to parse. |
error | if an error occurred, `NULL` is returned and this is filled with the message. |

#### Returns

a GrssFeedChannel, or `NULL` if an error occurs.

### grss_feed_channel_new_from_file ()

    GrssFeedChannel *
    grss_feed_channel_new_from_file (const gchar *path,
                                     GError **error);

Allocates a new GrssFeedChannel and init it with contents found in specified file.

#### Parameters

path | path of the file to parse. |
error | if an error occurred, `NULL` is returned and this is filled with the message. |

#### Returns

a GrssFeedChannel, or `NULL` if the file in `path` is not a valid document.

### grss_feed_channel_set_format ()

    void
    grss_feed_channel_set_format (GrssFeedChannel *channel,
                                  gchar *format);

To assign a file format to the feed.

#### Parameters

channel | a GrssFeedChannel. |
format | format of the file, such as "application/atom+xml" or "application/rss+xml". |

### grss_feed_channel_get_format ()

    const gchar *
    grss_feed_channel_get_format (GrssFeedChannel *channel);

Retrieves the file format of `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

file format of channel.

### grss_feed_channel_set_source ()

    gboolean
    grss_feed_channel_set_source (GrssFeedChannel *channel,
                                  gchar *source);

To assign the URL where to fetch the feed.

#### Parameters

channel | a GrssFeedChannel. |
source | URL of the feed. |

#### Returns

`TRUE` if `source` is a valid URL, `FALSE` otherwise

### grss_feed_channel_get_source ()

    const gchar *
    grss_feed_channel_get_source (GrssFeedChannel *channel);

Retrieves URL where to fetch the `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

URL of the channel.

### grss_feed_channel_set_title ()

    void
    grss_feed_channel_set_title (GrssFeedChannel *channel,
                                 gchar *title);

To set a title to the `channel` .

#### Parameters

channel | a GrssFeedChannel. |
title | title of the feed. |

### grss_feed_channel_get_title ()

    const gchar *
    grss_feed_channel_get_title (GrssFeedChannel *channel);

Retrieves title of the `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

title of the feed, or `NULL`.

### grss_feed_channel_set_homepage ()

    gboolean
    grss_feed_channel_set_homepage (GrssFeedChannel *channel,
                                    gchar *homepage);

To set the homepage of the site the `channel` belongs.

#### Parameters

channel | a GrssFeedChannel. |
homepage | homepage for the main website. |

#### Returns

`TRUE` if `homepage` is a valid URL, `FALSE` otherwise

### grss_feed_channel_get_homepage ()

    const gchar *
    grss_feed_channel_get_homepage (GrssFeedChannel *channel);

Retrieves the homepage of the site for which `channel` is the feed.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

reference homepage of the feed, or `NULL`.

### grss_feed_channel_set_description ()

    void
    grss_feed_channel_set_description (GrssFeedChannel *channel,
                                       gchar *description);

To set the description of `channel` .

#### Parameters

channel | a GrssFeedChannel. |
description | description of the feed. |

### grss_feed_channel_get_description ()

    const gchar *
    grss_feed_channel_get_description (GrssFeedChannel *channel);

Retrieves the description of `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

description of the feed, or `NULL`.

### grss_feed_channel_set_image ()

    gboolean
    grss_feed_channel_set_image (GrssFeedChannel *channel,
                                 gchar *image);

To set a rappresentative image to `channel` .

#### Parameters

channel | a GrssFeedChannel. |
image | URL of the image. |

#### Returns

`TRUE` if `image` is a valid URL, `FALSE` otherwise

### grss_feed_channel_get_image ()

    const gchar *
    grss_feed_channel_get_image (GrssFeedChannel *channel);

Retrieves the URL of the image assigned to the channel.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

URL of the image, or `NULL`.

### grss_feed_channel_set_icon ()

    gboolean
    grss_feed_channel_set_icon (GrssFeedChannel *channel,
                                gchar *icon);

To set the URL of the icon rappresenting `channel` .

#### Parameters

channel | a GrssFeedChannel. |
icon | URL where to retrieve the favicon. |

#### Returns

`TRUE` if `icon` is a valid URL, `FALSE` otherwise

### grss_feed_channel_get_icon ()

    const gchar *
    grss_feed_channel_get_icon (GrssFeedChannel *channel);

Retrieves URL of the favicon of the channel (and/or the website for which this is the feed).

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

URL of the favicon, or `NULL`.

### grss_feed_channel_set_language ()

    void
    grss_feed_channel_set_language (GrssFeedChannel *channel,
                                    gchar *language);

To set the language of `channel` .

#### Parameters

channel | a GrssFeedChannel. |
language | string holding the language of the feed. |

### grss_feed_channel_get_language ()

    const gchar *
    grss_feed_channel_get_language (GrssFeedChannel *channel);

Retrieves the language of the `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

string rappresenting the language of channel, or `NULL`.

### grss_feed_channel_set_category ()

    void
    grss_feed_channel_set_category (GrssFeedChannel *channel,
                                    gchar *category);

To set the category of the `channel` .

#### Parameters

channel | a GrssFeedChannel. |
category | category of the feed. |

### grss_feed_channel_get_category ()

    const gchar *
    grss_feed_channel_get_category (GrssFeedChannel *channel);

Retrieves category of the `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

category of the feed, or `NULL`.

### grss_feed_channel_set_pubsubhub ()

    gboolean
    grss_feed_channel_set_pubsubhub (GrssFeedChannel *channel,
                                     gchar *hub);

To set information about PubSubHubbub for the channel. To unset the hub, pass `NULL` as parameter.

#### Parameters

channel | a GrssFeedChannel. |
hub | hub for the feed, or `NULL`. |

#### Returns

`TRUE` if `hub` is a valid URL, `FALSE` otherwise

### grss_feed_channel_get_pubsubhub ()

    gboolean
    grss_feed_channel_get_pubsubhub (GrssFeedChannel *channel,
                                     gchar **hub);

Retrieves information about the PubSubHubbub hub of the channel.

#### Parameters

channel | a GrssFeedChannel. |
hub | location for the hub string, or `NULL`. |

#### Returns

`TRUE` if a valid PubSubHubbub hub has been set for the `channel` , `FALSE` otherwise.

### grss_feed_channel_set_rsscloud ()

    void
    grss_feed_channel_set_rsscloud (GrssFeedChannel *channel,
                                    gchar *path,
                                    gchar *protocol);

To set information about RSSCloud notifications for the channel.

#### Parameters

channel | a GrssFeedChannel. |
path | complete references of the URL where to register subscription, e.g. http://example.com/rsscloudNotify . |
protocol | type of protocol used for notifications. |

### grss_feed_channel_get_rsscloud ()

    gboolean
    grss_feed_channel_get_rsscloud (GrssFeedChannel *channel,
                                    gchar **path,
                                    gchar **protocol);

Retrieves information about the RSSCloud coordinates of the channel.

#### Parameters

channel | a GrssFeedChannel. |
path | location for the path string, or `NULL`. |
protocol | location for the protocol string, or `NULL`. |

#### Returns

`TRUE` if a valid RSSCloud path has been set for the `channel` , `FALSE` otherwise.

### grss_feed_channel_set_copyright ()

    void
    grss_feed_channel_set_copyright (GrssFeedChannel *channel,
                                     gchar *copyright);

To set the copyright of the feed.

#### Parameters

channel | a GrssFeedChannel. |
copyright | copyright of the channel. |

### grss_feed_channel_get_copyright ()

    const gchar *
    grss_feed_channel_get_copyright (GrssFeedChannel *channel);

Retrieves indications about the copyright.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

copyright of the `channel` , or `NULL`.

### grss_feed_channel_set_editor ()

    void
    grss_feed_channel_set_editor (GrssFeedChannel *channel,
                                  GrssPerson *editor);

To set the editor of the `channel` .

#### Parameters

channel | a GrssFeedChannel. |
editor | a GrssPerson. |

### grss_feed_channel_get_editor ()

    GrssPerson *
    grss_feed_channel_get_editor (GrssFeedChannel *channel);

Retrieves reference to the editor or the `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

GrssPerson, or `NULL`.

### grss_feed_channel_add_contributor ()

    void
    grss_feed_channel_add_contributor (GrssFeedChannel *channel,
                                       GrssPerson *contributor);

To add a contributor to the `channel` .

#### Parameters

channel | a GrssFeedChannel. |
contributor | a GrssPerson. |

### grss_feed_channel_get_contributors ()

    const GList *
    grss_feed_channel_get_contributors (GrssFeedChannel *channel);

Retrieves reference to the contributors of the `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

list of contributors to the channel, or `NULL`.

[element-type GrssPerson][transfer none]

### grss_feed_channel_add_cookie ()

    void
    grss_feed_channel_add_cookie (GrssFeedChannel *channel,
                                  SoupCookie *cookie);

To add a cookie related to the `channel` , will be involved in HTTP sessions while fetching it. More cookie can be added to every GrssFeedChannel

#### Parameters

channel | a GrssFeedChannel. |
cookie | HTML cookie to add to the GrssFeedChannel's cookie jar |

### grss_feed_channel_get_cookies ()

    GSList *
    grss_feed_channel_get_cookies (GrssFeedChannel *channel);

Retrieves reference to the HTML cookies of the `channel` . The list and the individual cookies should all be freed after use. You can use soup_cookies_free.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

list of cookies to the channel, or `NULL`.

[element-type SoupCookie][transfer full]

### grss_feed_channel_set_webmaster ()

    void
    grss_feed_channel_set_webmaster (GrssFeedChannel *channel,
                                     gchar *webmaster);

To assign a webmaster to the `channel` .

#### Parameters

channel | a GrssFeedChannel. |
webmaster | webmaster of the feed. |

### grss_feed_channel_get_webmaster ()

    const gchar *
    grss_feed_channel_get_webmaster (GrssFeedChannel *channel);

Retrieves reference to the webmaster of the feed.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

webmaster of `channel` , or `NULL`.

### grss_feed_channel_set_generator ()

    void
    grss_feed_channel_set_generator (GrssFeedChannel *channel,
                                     gchar *generator);

To set information about the software generator of `channel` .

#### Parameters

channel | a GrssFeedChannel. |
generator | software generator of the feed. |

### grss_feed_channel_get_generator ()

    const gchar *
    grss_feed_channel_get_generator (GrssFeedChannel *channel);

Retrieves information about the feed's software generator.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

generator of `channel` , or `NULL`.

### grss_feed_channel_set_gzip_compression ()

    void
    grss_feed_channel_set_gzip_compression
                                   (GrssFeedChannel *channel,
                                    gboolean value);

Set the GZIP compression for the channel to on or off.

#### Parameters

channel | a GrssFeedChannel. |
value | `TRUE` to enable GZIP compression when fetching the channel |

### grss_feed_channel_get_gzip_compression ()

    gboolean
    grss_feed_channel_get_gzip_compression
                                   (GrssFeedChannel *channel);

GZIP compression of the channel is either on or off.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

`TRUE` if `channel` has GZIP compression on.

### grss_feed_channel_set_publish_time ()

    void
    grss_feed_channel_set_publish_time (GrssFeedChannel *channel,
                                        time_t publish);

To set the time of publishing for the feed.

#### Parameters

channel | a GrssFeedChannel. |
publish | timestamp of publishing. |

### grss_feed_channel_get_publish_time ()

    time_t
    grss_feed_channel_get_publish_time (GrssFeedChannel *channel);

Retrieves the publishing time of `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

time of feed's publish.

### grss_feed_channel_set_update_time ()

    void
    grss_feed_channel_set_update_time (GrssFeedChannel *channel,
                                       time_t update);

To set the latest update time of `channel` .

#### Parameters

channel | a GrssFeedChannel. |
update | update time of the feed. |

### grss_feed_channel_get_update_time ()

    time_t
    grss_feed_channel_get_update_time (GrssFeedChannel *channel);

Retrieves the update time of `channel` .

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

time of the feed's latest update. If this value was not set (with `grss_feed_channel_set_update_time()`) returns `grss_feed_channel_get_publish_time()`.

### grss_feed_channel_set_update_interval ()

    void
    grss_feed_channel_set_update_interval (GrssFeedChannel *channel,
                                           int minutes);

To set the update interval for `channel` .

#### Parameters

channel | a GrssFeedChannel. |
minutes | update interval, in minutes. |

### grss_feed_channel_get_update_interval ()

    int
    grss_feed_channel_get_update_interval (GrssFeedChannel *channel);

Retrieves the update interval for the feed. Pay attention to the fact the value can be unset, and the function returns 0: in this case the caller must manually set a default update interval with `grss_feed_channel_set_update_interval()`.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

update interval for the `channel` , in minutes.

### grss_feed_channel_fetch ()

    gboolean
    grss_feed_channel_fetch (GrssFeedChannel *channel,
                             GError **error);

Utility to fetch and populate a GrssFeedChannel for the first time, and init all his internal values. Only the source URL has to be set in `channel` (with `grss_feed_channel_set_source()`). Be aware this function is sync, do not returns until the feed isn't downloaded and parsed.

#### Parameters

channel | a GrssFeedChannel. |
error | if an error occurred, `FALSE` is returned and this is filled with the message. |

#### Returns

`TRUE` if the feed is correctly fetched and parsed, `FALSE` otherwise.

### grss_feed_channel_fetch_async ()

    void
    grss_feed_channel_fetch_async (GrssFeedChannel *channel,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Similar to `grss_feed_channel_fetch()`, but asyncronous.

#### Parameters

channel | a GrssFeedChannel. |
callback | function to invoke at the end of the download. |
user_data | data passed to the callback. |

### grss_feed_channel_fetch_finish ()

    gboolean
    grss_feed_channel_fetch_finish (GrssFeedChannel *channel,
                                    GAsyncResult *res,
                                    GError **error);

Finalizes an asyncronous operation started with `grss_feed_channel_fetch_async()`.

#### Parameters

channel | a GrssFeedChannel. |
res | the GAsyncResult passed to the callback. |
error | if an error occurred, `FALSE` is returned and this is filled with the message. |

#### Returns

`TRUE` if `channel` informations have been successfully fetched, `FALSE` otherwise.

### grss_feed_channel_fetch_all ()

    GList *
    grss_feed_channel_fetch_all (GrssFeedChannel *channel,
                                 GError **error);

Utility to fetch and populate a GrssFeedChannel, and retrieve all its items.

#### Parameters

channel | a GrssFeedChannel. |
error | if an error occurred, `NULL` is returned and this is filled with the message. |

#### Returns

a GList of GrssFeedItem, to be completely unreferenced and freed when no longer in use, or `NULL` if an error occurs.

[element-type GrssFeedItem][transfer full]

### grss_feed_channel_fetch_all_async ()

    void
    grss_feed_channel_fetch_all_async (GrssFeedChannel *channel,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Similar to `grss_feed_channel_fetch_all()`, but asyncronous.

#### Parameters

channel | a GrssFeedChannel. |
callback | function to invoke at the end of the download. |
user_data | data passed to the callback. |

### grss_feed_channel_fetch_all_finish ()

    GList *
    grss_feed_channel_fetch_all_finish (GrssFeedChannel *channel,
                                        GAsyncResult *res,
                                        GError **error);

Finalizes an asyncronous operation started with `grss_feed_channel_fetch_all_async()`.

#### Parameters

channel | a GrssFeedChannel. |
res | the GAsyncResult passed to the callback. |
error | if an error occurred, `NULL` is returned and this is filled with the message. |

#### Returns

list of items fetched from the GrssFeedChannel, or `NULL` if `error` is set. The list (and contained items) is freed at the end of the callback.

[element-type GrssFeedItem][transfer none]

### grss_feed_channel_fetch_cancel ()

    gboolean
    grss_feed_channel_fetch_cancel (GrssFeedChannel *channel);

If a fetch operation was scheduled with `grss_feed_channel_fetch_async()` or `grss_feed_channel_fetch_all_async()`, cancel it.

#### Parameters

channel | a GrssFeedChannel. |

#### Returns

`TRUE` if a fetch was scheduled (and now cancelled), `FALSE` if this function had nothing to do

## Types and Values

### GRSS_FEED_CHANNEL_TYPE

    #define GRSS_FEED_CHANNEL_TYPE		(grss_feed_channel_get_type())