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.