# RSS
Author: Arvid Norberg, arvid@rasterbar.com

Author: | Arvid Norberg, arvid@rasterbar.com
Version: | 1.0.0

Table of contents

- feed_item
- feed_settings
- feed_status
- feed_handle

# feed_item

Declared in "libtorrent/rss.hpp"

represents one item from an RSS feed. Specifically a feed of torrents.

    struct feed_item
    {
       feed_item ();
       ~feed_item ();

       std::string url;
       std::string uuid;
       std::string title;
       std::string description;
       std::string comment;
       std::string category;
       size_type size;
       torrent_handle handle;
       sha1_hash info_hash;
    };

url uuid title description comment category
  these are self explanatory and may be empty if the feed does not specify those fields.

size
  the total size of the content the torrent refers to, or -1 if no size was specified by the feed.

handle
  the handle to the torrent, if the session is already downloading this torrent.

info_hash
  the info-hash of the torrent, or cleared (i.e. all zeroes) if the feed does not specify the info-hash.

# feed_settings

Declared in "libtorrent/rss.hpp"

the feed_settings object is all the information and configuration for a specific feed. All of these settings can be changed by the user after adding the feed

    struct feed_settings
    {
       feed_settings ();

       std::string url;
       bool auto_download;
       bool auto_map_handles;
       int default_ttl;
       add_torrent_params add_args;
    };

auto_download
  By default `auto_download` is true, which means all torrents in the feed will be downloaded. Set this to false in order to manually add torrents to the session. You may react to the rss_alert when a feed has been updated to poll it for the new items in the feed when adding torrents manually. When torrents are added automatically, an add_torrent_alert is posted which includes the torrent handle as well as the error code if it failed to be added. You may also call `session::get_torrents()` to get the handles to the new torrents.

auto_map_handles
  `auto_map_handles` defaults to true and determines whether or not to set the `handle` field in the feed_item, returned as the feed status. If auto-download is enabled, this setting is ignored. If auto-download is not set, setting this to false will save one pass through all the feed items trying to find corresponding torrents in the session.

default_ttl
  The `default_ttl` is the default interval for refreshing a feed. This may be overridden by the feed itself (by specifying the `<ttl>` tag) and defaults to 30 minutes. The field specifies the number of minutes between refreshes.

add_args
  If torrents are added automatically, you may want to set the `add_args` to appropriate values for download directory etc. This object is used as a template for adding torrents from feeds, but some torrent specific fields will be overridden by the individual torrent being added. For more information on the add_torrent_params, see async_add_torrent() and add_torrent().

# feed_status

Declared in "libtorrent/rss.hpp"

holds information about the status of an RSS feed. Retrieved by calling get_feed_status() on feed_handle.

    struct feed_status
    {
       feed_status ();

       std::string url;
       std::string title;
       std::string description;
       time_t last_update;
       int next_update;
       bool updating;
       std::vector<feed_item> items;
       error_code error;
       int ttl;
    };

url
  the URL of the feed.

title
  the name of the feed (as specified by the feed itself). This may be empty if we have not recevied a response from the RSS server yet, or if the feed does not specify a title.

description
  the feed description (as specified by the feed itself). This may be empty if we have not received a response from the RSS server yet, or if the feed does not specify a description.

last_update
  the posix time of the last successful response from the feed.

next_update
  the number of seconds, from now, when the feed will be updated again.

updating
  true if the feed is currently being updated (i.e. waiting for DNS resolution, connecting to the server or waiting for the response to the HTTP request, or receiving the response).

items
  a vector of all items that we have received from the feed. See feed_item for more information.

error
  set to the appropriate error code if the feed encountered an error. See error_code for more info.

ttl
  the current refresh time (in minutes). It's either the configured default ttl, or the ttl specified by the feed.

# feed_handle

Declared in "libtorrent/rss.hpp"

The `feed_handle` refers to a specific RSS feed that is watched by the session.

    struct feed_handle
    {
       feed_handle ();
       void update_feed ();
       feed_status get_feed_status () const;
       void set_settings (feed_settings const& s);
       feed_settings settings () const;
    };

## update_feed()

    void update_feed ();

Forces an update/refresh of the feed. Regular updates of the feed is managed by libtorrent, be careful to not call this too frequently since it may overload the RSS server.

## get_feed_status()

    feed_status get_feed_status () const;

Queries the RSS feed for information, including all the items in the feed. see feed_status.

## settings() set_settings()

    void set_settings (feed_settings const& s);
    feed_settings settings () const;

Sets and gets settings for this feed. For more information on the available settings, see add_feed().

## add_feed_item()

Declared in "libtorrent/rss.hpp"

    torrent_handle add_feed_item (session& s, feed_item const& fi
       , add_torrent_params const& p);
    torrent_handle add_feed_item (session& s, feed_item const& fi
       , add_torrent_params const& p, error_code& ec);

given a feed_item `f`, add the torrent it refers to to session `s`.

## new_feed()

Declared in "libtorrent/rss.hpp"

    boost::shared_ptr<feed> new_feed (aux::session_impl& ses, feed_settings const& sett);