INN::ovsqlite_client(3pm)

NAME
INN::ovsqlite_client - Talk to ovsqlite-server from Perl

SYNOPSIS
    use INN::ovsqlite_client qw(:all);

    my $client = INN::ovsqlite_client::->new(
        port => "/usr/local/news/run/ovsqlite.sock",
    );

    $client->search_group_all(
        groupname => "news.software.nntp",
        low       => 1,
        cols      => search_col_overview,
        errmsg    => my $errmsg,
        callback  => sub {
            my ($articles) = @_;

            foreach my $article (@{$articles}) {
                print $article->{overview};
            }
            1;
        },
    );

    defined($errmsg)
      and die "search_group_all: $errmsg";

DESCRIPTION
"INN::ovsqlite_client" implements the binary protocol used to communicate with the ovsqlite-server daemon. It offers one instance method for each request type plus convenience methods for those requests that need to be repeated. See ovsqlite-private.h for details.

Two examples of use within a Perl script are present in the contrib directory (ovsqlite-dump and ovsqlite-undump).

EXPORTS

tag :search_cols
    Flags to select what optional information the "search_group" method should return.

    search_col_arrived
    search_col_expires
    search_col_token
    search_col_overview

tag :response_codes
    Success responses:

    response_ok
    response_done
    response_groupinfo
    response_grouplist
    response_grouplist_done
    response_artinfo
    response_artlist
    response_artlist_done

    Error responses:

    response_error
    response_sequence_error
    response_sql_error
    response_corrupted
    response_no_group
    response_no_article
    response_dup_article
    response_old_article

    Fatal error responses:

    response_fatal
    response_bad_request
    response_oversized
    response_wrong_state
    response_wrong_version
    response_failed_auth

tag :all
    All of the above.

CONSTRUCTOR
    $client = INN::ovsqlite_client::->new(
        path => $path,
        mode => $mode,         # optional, default 0 (read only)
    );

Croaks on failure.

METHODS
All request methods return the response code and store any error message in the optional "errmsg" named argument.

Communication or protocol errors (as opposed to server errors) cause croaks.

set_cutofflow
        $code = $client->set_cutofflow(
            cutofflow  => $cutofflow,     # optional, default 0 (false)
            errmsg     => $errmsg,        # optional output
        );

add_group
        $code = $client->add_group(
            groupname  => $groupname,
            low        => $low,
            high       => $high,
            flag_alias => $flag_alias,
            errmsg     => $errmsg,        # optional output
        );

get_groupinfo
        $code = $client->get_groupinfo(
            groupname  => $groupname,
            low        => $low,           # optional output
            high       => $high,          # optional output
            count      => $count,         # optional output
            flag_alias => $flag_alias,    # optional output
            errmsg     => $errmsg,        # optional output
        );

delete_group
        $code = $client->delete_group(
            groupname  => $groupname,
            errmsg     => $errmsg,        # optional output
        );

list_groups
        $code = $client->list_groups(
            groupid    => $groupid,       # optional in/output, default 0
            readsize   => $readsize,      # optional, default 0x20000
            groups     => $groups,        # output
            errmsg     => $errmsg,        # optional output
        );

    $groups is set to a reference to an array of references to hashes with these keys:

    groupname
    low
    high
    count
    flag_alias

list_groups_all
        $code = $client->list_groups_all(
            callback   => \&callback,
            readsize   => $readsize,      # optional, default 0x20000
            errmsg     => $errmsg,        # optional output
        );

    This convenience method calls "list_groups" repeatedly to fetch information for all groups. The callback function is called with the groups array reference as the only argument. It should return a true value to keep iterating or a false value to terminate.

add_article
        $code = $client->add_artice(
            groupname  => $groupname,
            artnum     => $artnum,
            token      => $token,
            arrived    => $arrived,       # optional, default 0
            expires    => $expires,       # optional, default 0
            overview   => $overview,
            errmsg     => $errmsg,        # optional output
        );

get_artinfo
        $code = $client->get_artinfo(
            groupname  => $groupname,
            artnum     => $artnum,
            token      => $token,         # output
            errmsg     => $errmsg,        # optional output
        );

delete_article
        $code = $client->delete_article(
            groupname  => $groupname,
            artnum     => $artnum,
            errmsg     => $errmsg,        # optional output
        );

search_group
        $code = $client->search_group(
            groupname  => $groupname,
            low        => $low,
            high       => $high,          # optional
            cols       => $cols,          # optional, default 0x00
            readsize   => $readsize,      # optional, default 0x20000
            articles   => $articles,      # output
            errmsg     => $errmsg,        # optional output
        );

    $articles is set to a reference to an array of references to hashes with these keys:

    artnum
    arrived
    expires
    token
    overview

search_group_all
        $code = $client->search_group_all(
            groupname  => $groupname,
            low        => $low,
            high       => $high,          # optional
            cols       => $cols,          # optional, default 0x00
            callback   => \&callback,
            readsize   => $readsize,      # optional, default 0x20000
            errmsg     => $errmsg,        # optional output
        );

    This convenience methods calls "search_group" repeatedly to fetch information for all specified articles. The callback function is called with the articles array reference as the only argument. It should return a true value to keep iterating or a false value to terminate.

start_expire_group
        $code = $client->start_expire_group(
            groupname  => $groupname,
            errmsg     => $errmsg,        # optional output
        );

expire_group
        $code = $client->expire_group(
            groupname  => $groupname,
            artnums    => \@artnums,
            errmsg     => $errmsg,        # optional output
        );

    @artnums must be an array of article numbers.

finish_expire
        $code = $client->finish_expire(
            errmsg     => $errmsg,        # optional output
        );

finish_expire_all
        $code = $client->finish_expire_all(
            callback   => \&callback,
            errmsg     => $errmsg,        # optional output
        );

    This convenience method calls "finish_expire" repeatedly until done. The callback function is called with no arguments and should return a true value to keep iterating or a false value to terminate.

HISTORY
Initial implementation and documentation written by Bo Lindbergh for InterNetNews.

SEE ALSO
perl(1), ovsqlite-server(8).