view release on metacpan or  search on metacpan

lib/Net/BitTorrentSync.pm  view on Meta::CPAN

# ABSTRACT: Perl wrapper for the BitTorrent Sync API
package Net::BitTorrentSync;

use strict;
use warnings;

# for now, check switching to HTTP::Tiny or Hijk
use LWP::Simple;
use JSON;

use Exporter;
our @ISA = 'Exporter';

our @EXPORT = qw(
    start_btsync
    set_config
    set_listened_address
    add_folder
    get_folders
    remove_folder
    get_files
    set_file_prefs
    get_folder_peers
    get_secrets
    get_folder_prefs
    set_folder_prefs
    get_folder_hosts
    set_folder_hosts
    get_prefs
    set_prefs
    get_os
    get_version
    get_speed
    shutdown_btsync
);

our $VERSION = '0.21';

my ($config, $listen);

=head1 NAME

Net::BitTorrentSync - A Perl interface to the BitTorrent Sync API

=head1 VERSION

version 0.21

=head1 SYNOPSIS

    use Net::BitTorrentSync;

    start_btsync('/path/to/btsync_executable', '/path/to/config_file');

or

    set_config('/path/to/config_file');

or

    set_listened_path('127.0.0.1:8888');

then

    add_folder('/path/to/folder');

    my $folders = get_folders();

    remove_folder($folders->[0]->{secret});


=head1 DESCRIPTION

BitTorrent Sync uses the BitTorrent protocol to sync files between
two or more machines, or nodes (computers or mobile phones) without
the need of a server. It uses "secrets", a unique hash string given
for each folder that replaces the need for a tracker machine.
The more nodes the network has, the faster the data will be synched
between the nodes, allowing for very fast exchange rates.
In addition, folders and files can be shared as read-only, or as
read and write.

This is a complete wrapper of the published BitTorrent Sync API.
It can be used to connect your Perl application to a running
BitTorrent Sync instance, in order to perform any action such as
adding, removing folders/files, querying them, setting preferences,
and fetch information about the BitTorrent Sync instance.

=head1 !WARNING!

lib/Net/BitTorrentSync.pm  view on Meta::CPAN

=item secret (required)

Specifies folder secret

=back

=cut

sub remove_folder {
    my ($secret) = @_;
    my $request = "remove_folder&secret=$secret";

    return _access_api($request);
}

=head2 get_files

Returns list of files within the specified directory.
If a directory is not specified, will return list of files and folders within
the root folder.
Note that the Selective Sync function is only available in the API at this time.

    [
        {
            name  => "images",
            state => "created",
            type  => "folder"
        },
        {
            have_pieces  => 1,
            name         => "index.html",
            size         => 2726,
            state        => "created",
            total_pieces => 1,
            type         => "file",
            download     => 1 # only for selective sync folders
        }
    ]

=over 4

=item secret (required)

=item path (optional)

Specifies path to a subfolder of the sync folder.

=back

=cut

sub get_files {
    my ($secret, $path) = @_;
    my $request = "get_files&secret=$secret";

    $request .= "&path=$path" if $path;

    return _access_api($request);
}

=head2 set_file_prefs

Selects file for download for selective sync folders.
Returns file information with applied preferences.

=over 4

=item secret (required)

=item path (required)

Specifies path to a subfolder of the sync folder.

=item download (required)

Specifies if file should be downloaded (yes - 1, no - 0)

=back

=cut

sub set_file_prefs {
    my ($secret, $path, $download) = @_;
    my $request = "get_files&secret=$secret&path=$path&download=$download";

    return _access_api($request);
}

=head2 get_folder_peers

Returns list of peers connected to the specified folder.

    [
        {
            id         => "ARRdk5XANMb7RmQqEDfEZE-k5aI=",
            connection => "direct", # direct or relay
            name       => "GT-I9500",
            synced     => 0, # timestamp when last sync completed
            download   => 0,
            upload     => 22455367417
        }
    ]

=over 4

=item secret (required)

=back

=cut

sub get_folder_peers {
    my ($secret) = @_;
    my $request = "get_folder_peers&secret=$secret";
    return _access_api($request);
}

=head2 get_secrets

Generates read-write, read-only and encryption read-only secrets.
If ‘secret’ parameter is specified,
will return secrets available for sharing under this secret.
The Encryption Secret is new functionality.
This is a secret for a read-only peer with encrypted content
(the peer can sync files but can not see their content).
One example use is if a user wanted to backup files to an untrusted,
unsecure, or public location.
This is set to disabled by default for all users but included in the API.

    {
        read_only  => "ECK2S6MDDD7EOKKJZOQNOWDTJBEEUKGME",
        read_write => "DPFABC4IZX33WBDRXRPPCVYA353WSC3Q6",
        encryption => "G3PNU7KTYM63VNQZFPP3Q3GAMTPRWDEZ"
    }

=over 4

=item secret (required)

=item type (optional)

If type = encrypted, generate secret with support of encrypted peer

=back

NOTE: there seems to be some contradiction in the documentation
wrt to secret being required.

=cut

sub get_secrets {
    my ($secret, $type) = @_;

    my $request = "get_secrets";
    $request .= "&secret=$secret" if $secret;
    $request .= "&type=encryption" if $type;
    return _access_api($request);
}

=head2 get_folder_prefs

Returns preferences for the specified sync folder.

    {
        search_lan       => 1,
        use_dht          => 0,
        use_hosts        => 0,
        use_relay_server => 1,
        use_sync_trash   => 1,
        use_tracker      => 1
    }

=over 4

=item secret (required)

=back

=cut

sub get_folder_prefs {
    my ($secret) = @_;
    my $request = "get_folder_prefs&secret=$secret";
    return _access_api($request);
}

=head2 set_folder_prefs

Sets preferences for the specified sync folder.
Parameters are the same as in ‘Get folder preferences’.
Returns current settings.

=over 4

=item secret (required)

=item preferences

A hashref containing the preferences you wish to change.

=over 4

=item use_dht

=item use_hosts

=item search_lan

=item use_relay_server

=item use_tracker

=item use_sync_trash

=back

=back

=cut

sub set_folder_prefs {
    my ($secret, $prefs) = @_;
    my $request = "set_folder_prefs&secret=$secret";

    foreach my $pref (keys %{$prefs}) {
        $request .= '&' . $pref . '=' . $prefs->{$pref};
    }

    return _access_api($request);
}

=head2 get_folder_hosts

Returns list of predefined hosts for the folder,
or error code if a secret is not specified.

    {
        hosts => [
           "192.168.1.1:4567",
           "example.com:8975"
        ]
    }

=over 4

=item secret (required)

=back

=cut

sub get_folder_hosts {
    my ($secret) = @_;
    my $request = "get_folder_hosts&secret=$secret";
    return _access_api($request);
}

=head2 set_folder_hosts

Sets one or several predefined hosts for the specified sync folder.
Existing list of hosts will be replaced.
Hosts should be added as values of the ‘host’ parameter and separated by commas.
Returns current hosts if set successfully, error code otherwise.

=over 4

=item secret (required)

=item hosts (required)

List of hosts, each host should be represented as “[address]:[port]”

=back

=cut

sub set_folder_hosts {
    my ($secret, $hosts) = @_;
    my $request = "set_folder_hosts&secret=$secret&hosts=";

    $request .= join ',', @{$hosts};

    return _access_api($request);
}

=head2 get_prefs

Returns BitTorrent Sync preferences.
Contains dictionary with advanced preferences.
Please see Sync user guide for description of each option.

    {
        device_name                     => "iMac",
        disk_low_priority               => "true",
        download_limit                  => 0,
        folder_rescan_interval          => "600",
        lan_encrypt_data                => "true",
        lan_use_tcp                     => "false",
        lang                            => -1,
        listening_port                  => 11589,
        max_file_size_diff_for_patching => "1000",
        max_file_size_for_versioning    => "1000",
        rate_limit_local_peers          => "false",
        send_buf_size                   => "5",
        sync_max_time_diff              => "600",
        sync_trash_ttl                  => "30",
        upload_limit                    => 0,
        use_upnp                        => 0,
        recv_buf_size                   => "5"
    }

=cut

sub get_prefs {
    return _access_api("get_prefs");
}

=head2 set_prefs

Sets BitTorrent Sync preferences.
Parameters are the same as in ‘Get preferences’.
Advanced preferences are set as general settings. Returns current settings.

=over 4

=item preferences (required)

A hashref (see get_prefs) containing the preferences you wish to change.

=back

=cut

sub set_prefs {
    my ($secret, $prefs) = @_;
    my $request = "set_prefs";

    foreach my $pref (keys %{$prefs}) {
        $request .= '&' . $pref . '=' . $prefs->{$pref};
    }

    return _access_api($request);
}

=head2 get_os

Returns OS name where BitTorrent Sync is running.

    {
        os => "win32"
    }

=cut

sub get_os {
    return _access_api("get_os");
}

=head2 get_version

Returns BitTorrent Sync version.

    {
        version => "1.2.48"
    }

=cut

sub get_version {
    return _access_api("get_version");
}

=head2 get_speed

Returns current upload and download speed.

    {
        download => 61007,
        upload   => 0
    }

=cut

sub get_speed {
    return _access_api("get_speed");
}

=head2 shutdown

Gracefully stops Sync.

=cut

sub shutdown_btsync {
    return _access_api("shutdown");
}

sub _access_api {
    my $request = shift;