NAME

slackget10::Network - A class for network communication

VERSION

Version 0.7.3

SYNOPSIS

This class' purpose is to make all network dialog transparent. Instead of sending

    use slackget10::Network;

    my $net = slackget10::Network->new(
        handle_responses => 1,
        socket => IO::Socket::INET->new(
                PeerAddr => 192.168.0.10,
                PeerPort => 42000)
    );
    my $installed = $net->get_installed_list ;
    my $reponse = $net->install_packages("gcc-objc;gcc-g++;gcc");
    if($response->is_success)
    {
        print "Packages successfully installed\n";
    }
    elsif($response->have_choice)
    {
        print $response->data ;
    }
    elsif($response->is_error)
    {
        print "An error occured during install. Remote daemon said : ",$response->data ,"\n";
    }

All methods from this module return a slackget10::Network::Response (slackget10::Network::Response) object.

In the same way they all handle network exceptions from remote daemon.

CONSTRUCTOR

new

Need a 'socket' argument :

    my $net = slackget10::Network->new(
        socket => IO::Socket::INET->new(
                PeerAddr => 192.168.0.10,
                PeerPort => 42000)
    );

The constructor can take the followings arguments :

socket : a IO::Socket::INET wich is connected to the remote slack-getd

handle_responses : if this parameter is defined the slackget10::Network class instance will handle the network answer (default: undef).

WARNING: if you use this class on a GUI you will prefer to handle protocol by yourself because this class freeze a GUI. The other possibility is to use the network tasks manager class of slack-get (this class has been recoded for this manager, you can read slackget10::GUI::Qt::operationsProcessor for more informations).

WARNING 2 : For the moment, this class can only handle responses when you use an IO::Socket socket (no support for Qt::Socket yet).

slackget_object : a reference to a valide slackget10 object.

on_error [handler] : a CODE reference to a sub which will be call on each error message returned by the server. This sub must take a string (the error message) as argument.

on_success [handler] : a CODE reference to a sub which will be call on each success message returned by the server. This sub must take a string (the error message) as argument.

on_unknow [handler] : a CODE reference to a sub which will be call on each unknown command message returned by the remote slack-getd. This sub must take a string (the error message) as argument.

on_choice [handler] : a CODE reference to a sub wich will be call each time a choice is needed. This sub must take a whole XML string which represent the choice as argument. Please look at the source code of the on_choice method for more informations.

on_info [handler] : a CODE reference to a sub wich will be call each time the daemon give us an information. This sub must take as argument : an IP adresse (string), an info level (integer) and a message (string). Please remember that this message is only half process : this class extract the IP adresse of the remote daemon, the info level and the message, but the message itself can contains other informations which are not yet process (like "progress" messages).

There is also one special event : 'end' which is not hookable. It may be in the futur but this event is send when all treatment and data relative to the last command are terminate (but there is no information about the state in this event). It seems that this is usefull only to this module's methods.

Look at the "DEFAULT HANDLERS" section for more informations one default handlers.

FUNCTIONS

All methods return a slackget10::Network::Response (slackget10::Network::Response) object, and if the remote slack-getd return some data they are accessibles via the data() accessor of the slackget10::Network::Response object.

_setconnectionid

Set the id of the connection. The id is generate by the constructor and must not be modified. This method is automatically called by the constructor and is mostly private.

        $net->_setconnectionid() ;

send_data

send a given message to the remote daemon. This method is mostly for private use.

        $net->send_data("get_installed_list") or die "cannot send get_installed_list\n";

get_installed_list

get the list of installed packages on the remote daemon.

        my $installed_list = $net->get_installed_list ;

If an error occured call the appropriate handler.

In all case return a slackget10::Network::Response (slackget10::Network::Response) object.

get_packages_list

get the list of new avalaible packages on the remote daemon.

        my $status = $net->get_packages_list ;

If an error occured call the appropriate handler.

In all case return a slackget10::Network::Response (slackget10::Network::Response) object.

get_html_info

Get an HTML encoded string which give some general information on the remote slack-getd

        print $net->get_html_info ;

build_packages_list

Said to the remote slack-getd to build the new packages cache.

        my $status = $net->build_packages_list ;

The returned status contains no significant data in case of success.

build_installed_list

Said to the remote slack-getd to build the installed packages cache.

        my $status = $net->build_installed_list ;

The returned status contains no significant data in case of success.

build_media_list

Said to the remote slack-getd to build the media list (medias.xml file).

        my $status = $net->build_media_list ;

The returned status contains no significant data in case of success.

diskspace

Ask to the remote daemon for the state of the disk space on a specify partition.

        $net->handle_responses(1); # We want slackget10::Network handle the response and return the hashref.
        my $response = $net->diskspace( "/" ) ;
        $net->handle_responses(0);
        print "Free space on remote computer / directory is ",$response->data()->{avalaible_space}," KB\n";

Return a slackget10::Network::Response object which contains (in case of success) a HASHREF build like that :

        $space = {
                device => <NUMBER>,
                total_size => <NUMBER>,
                used_space => <NUMBER>,
                available_space => <NUMBER>,
                use_percentage => <NUMBER>,
                mount_point => <NUMBER>
        };

search

take at least two parameters : the word you search for, and a field. Valid fields are those who describe a package entity in the packages.xml file.

        my $response = $net->search('gcc','name','description') ; # search for package containing 'gcc' in fields 'name' and 'description'

Return the remote slack-getd's response in the DATA section of the response (slackget10::Network::Response).

websearch

Take 2 parameters : a reference on an array which contains the words to search for, and another array reference which contains a list of fields (valid fields are thoses describe in the packages.xml file).

The DATA section of the response (slackget10::Network::Response) will contain an ARRAYREF. Each cell of this array will contains a package in HTML The returned data is HTML, each package are separed by a line wich only contain the string "__MARK__"

        my $response = $network->websearch([ 'burn', 'cd' ], [ 'name', 'description' ]) ;

multisearch

The DATA section of the response (slackget10::Network::Response) will contain the XML encoded response.

        my $response = $network->websearch([ 'burn', 'cd' ], [ 'name', 'description' ]) ;

getfile

This method allow you to download one or more files from a slack-get daemon. This method of download is specific to slack-get and is based on the EBCS protocol.

Arguments are :

        files : pass a slackget10::PackageList to this option.
        
        destdir : a string wich is the directory where will be stored the downloaded files.

Here is a little code example :

        # $pkgl is a slackget10::PackageList object.
        $net->getfile(
                file => $pkgl,
                destdir => $sgo->config()->{common}->{'update-directory'}."/package-cache/"
        );

reboot

        This method ask the remote daemon to reboot the remote computer.

quit

Close the current connection.

        $net->quit ;

ACCESSORS

Socket (read only)

return the current socket (IO::Socket::INET) object.

Host

Call the peerhost() method of the current IO::Socket::INET object and return the result.

slackget (read only)

return the current slackget10 object.

get_connectionid

Return the (read-only) connection ID.

        $net->get_connectionid

handle_responses (read/write)

        Boolean accessor, get/set the value of the handle_responses option.

PKGTOOLS BINDINGS

Methods in this section are the remote call procedure for pkgtools interactions. The slack-getd daemon use another class for direct call to the pkgtools (slackget10::PkgTools).

The 3 methods have the same operating mode :

1) Take a single slackget10::PackageList as argument

2) Do the job

3) If their is more than one choice for the package you try to install, the daemon ask for a choice of you.

3bis) Re-do the job

4) For each package in the slackget10::PackageList set a 'status' field which contain the status of the (install|upgrade|remove) process.

installpkg

        $net->installpkg($packagelist) ;

upgradepkg

        $net->upgradepkg($packagelist) ;

removepkg

Send network commands to a slack-get daemon. This method (like other pkgtools network call), do nothing by herself, but sending a "removepkg:pkg1;pkg2;..;pkgN" to the slack-getd.

        $net->removepkg($packagelist) ;

DEFAULT HANDLERS