view release on metacpan or  search on metacpan

README  view on Meta::CPAN

THE AnyEvent::FCP CLASS
    $fcp = new AnyEvent::FCP key => value...;
        Create a new FCP connection to the given host and port (default
        127.0.0.1:9481, or the environment variables "FREDHOST" and
        "FREDPORT").

        If no "name" was specified, then AnyEvent::FCP will generate a
        (hopefully) unique client name for you.

        The following keys can be specified (they are all optional):

        name => $string
            A unique name to identify this client. If none is specified, a
            randomly generated name will be used.

        host => $hostname
            The hostname or IP address of the freenet node. Default is
            $ENV{FREDHOST} or 127.0.0.1.

        port => $portnumber
            The port number of the FCP port. Default is $ENV{FREDPORT} or
            9481.

        timeout => $seconds
            The timeout, in seconds, after which a connection error is
            assumed when there is no activity. Default is 7200, i.e. two
            hours.

        keepalive => $seconds
            The interval, in seconds, at which keepalive messages will be
            sent. Default is 540, i.e. nine minutes.

            These keepalive messages are useful both to detect that a
            connection is no longer working and to keep any (home) routers
            from expiring their masquerading entry.

        on_eof => $callback->($fcp)
            Invoked when the underlying AnyEvent::Handle signals EOF,
            currently regardless of whether the EOF was expected or not.

        on_error => $callback->($fcp, $message)
            Invoked on any (fatal) errors, such as unexpected connection
            close. The callback receives the FCP object and a textual error
            message.

        on_failure => $callback->($fcp, $type, $backtrace, $args, $error)
            Invoked when an FCP request fails that didn't have a failure
            callback. See "FCP REQUESTS" for details.

  FCP REQUESTS
    The following methods implement various requests. Most of them map
    directory to the FCP message of the same name. The added benefit of
    these over sending requests yourself is that they handle the necessary
    serialisation, protocol quirks, and replies.

    All of them exist in two versions, the variant shown in this manpage,
    and a variant with an extra "_" at the end, and an extra $cb argument.
    The version as shown is *synchronous* - it will wait for any replies,
    and either return the reply, or croak with an error. The underscore
    variant returns immediately and invokes one or more callbacks or
    condvars later.

    For example, the call

       $info = $fcp->get_plugin_info ($name, $detailed);

    Also comes in this underscore variant:

       $fcp->get_plugin_info_ ($name, $detailed, $cb);

    You can thinbk of the underscore as a kind of continuation indicator -
    the normal function waits and returns with the data, the "_" indicates
    that you pass the continuation yourself, and the continuation will be
    invoked with the results.

    This callback/continuation argument ($cb) can come in three forms
    itself:

    A code reference (or rather anything not matching some other
    alternative)
        This code reference will be invoked with the result on success. On
        an error, it will invoke the "on_failure" callback of the FCP
        object, or, if none was defined, will die (in the event loop) with a
        backtrace of the call site.

        This is a popular choice, but it makes handling errors hard - make
        sure you never generate protocol errors!

        If an "on_failure" hook exists, it will be invoked with the FCP
        object, the request type (the name of the method), a (textual)
        backtrace as generated by "Carp::longmess", and arrayref containing
        the arguments from the original request invocation and the error
        object from the server, in this order, e.g.:

           on_failure => sub {
              my ($fcp, $request_type, $backtrace, $orig_args, $error_object) = @_;

              warn "FCP failure ($type), $error_object->{code_description} ($error_object->{extra_description})$backtrace";
              exit 1;
           },

    A condvar (as returned by e.g. "AnyEvent->condvar")
        When a condvar is passed, it is sent ("$cv->send ($results)") the
        results when the request has finished. Should an error occur, the
        error will instead result in "$cv->croak ($error)".

        This is also a popular choice.

    An array with two callbacks "[$success, $failure]"
        The $success callback will be invoked with the results, while the
        $failure callback will be invoked on any errors.

        The $failure callback will be invoked with the error object from the
        server.

    "undef"
        This is the same thing as specifying "sub { }" as callback, i.e. on
        success, the results are ignored, while on failure, the "on_failure"
        hook is invoked or the module dies with a backtrace.

        This is good for quick scripts, or when you really aren't interested
        in the results.

    $peers = $fcp->list_peers ([$with_metdata[, $with_volatile]])
    $notes = $fcp->list_peer_notes ($node_identifier)
    $fcp->watch_global ($enabled[, $verbosity_mask])
    $reqs = $fcp->list_persistent_requests
    $sync = $fcp->modify_persistent_request ($global, $identifier[,
    $client_token[, $priority_class]])
        Update either the "client_token" or "priority_class" of a request
        identified by $global and $identifier, depending on which of
        $client_token and $priority_class are not "undef".

    $info = $fcp->get_plugin_info ($name, $detailed)
    $status = $fcp->client_get ($uri, $identifier, %kv)
        %kv can contain (<http://wiki.freenetproject.org/FCP2p0ClientGet>).

        ignore_ds, ds_only, verbosity, max_size, max_temp_size, max_retries,
        priority_class, persistence, client_token, global, return_type,
        binary_blob, allowed_mime_types, filename, temp_filename

    $status = $fcp->remove_request ($identifier[, $global])
        Remove the request with the given isdentifier. Returns true if
        successful, false on error.

    ($can_read, $can_write) = $fcp->test_dda ($local_directory,
    $remote_directory, $want_read, $want_write))
        The DDA test in FCP is probably the single most broken protocol -
        only one directory test can be outstanding at any time, and some
        guessing and heuristics are involved in mangling the paths.

        This function combines "TestDDARequest" and "TestDDAResponse" in one
        request, handling file reading and writing as well, and tries very
        hard to do the right thing.

        Both $local_directory and $remote_directory must specify the same
        directory - $local_directory is the directory path on the client
        (where AnyEvent::FCP runs) and $remote_directory is the directory
        path on the server (where the freenet node runs). When both are
        running on the same node, the paths are generally identical.

        $want_read and $want_write should be set to a true value when you
        want to read (get) files or write (put) files, respectively.

        On error, an exception is thrown. Otherwise, $can_read and
        $can_write indicate whether you can reaqd or write to freenet via
        the directory.

  REQUEST CACHE