.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "INN::ovsqlite_client 3pm"
.TH INN::ovsqlite_client 3pm 2026-06-12 "INN 2.7.4" "InterNetNews Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
INN::ovsqlite_client \- Talk to ovsqlite\-server from Perl
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    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";
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`INN::ovsqlite_client\*(C'\fR implements the binary protocol used to communicate
with the \fBovsqlite-server\fR daemon.  It offers one instance method for each
request type plus convenience methods for those requests that need to be
repeated.  See \fIovsqlite\-private.h\fR for details.
.PP
Two examples of use within a Perl script are present in the \fIcontrib\fR
directory (\fBovsqlite-dump\fR and \fBovsqlite-undump\fR).
.SH EXPORTS
.IX Header "EXPORTS"
.IP "tag :search_cols" 4
.IX Item "tag :search_cols"
Flags to select what optional information the \f(CW\*(C`search_group\*(C'\fR method should
return.
.RS 4
.IP search_col_arrived 8
.IX Item "search_col_arrived"
.PD 0
.IP search_col_expires 8
.IX Item "search_col_expires"
.IP search_col_token 8
.IX Item "search_col_token"
.IP search_col_overview 8
.IX Item "search_col_overview"
.RE
.RS 4
.PD
.Sp

.RE
.IP "tag :response_codes" 4
.IX Item "tag :response_codes"
Success responses:
.RS 4
.IP response_ok 8
.IX Item "response_ok"
.PD 0
.IP response_done 8
.IX Item "response_done"
.IP response_groupinfo 8
.IX Item "response_groupinfo"
.IP response_grouplist 8
.IX Item "response_grouplist"
.IP response_grouplist_done 8
.IX Item "response_grouplist_done"
.IP response_artinfo 8
.IX Item "response_artinfo"
.IP response_artlist 8
.IX Item "response_artlist"
.IP response_artlist_done 8
.IX Item "response_artlist_done"
.RE
.RS 4
.PD
.Sp

.Sp
Error responses:
.IP response_error 8
.IX Item "response_error"
.PD 0
.IP response_sequence_error 8
.IX Item "response_sequence_error"
.IP response_sql_error 8
.IX Item "response_sql_error"
.IP response_corrupted 8
.IX Item "response_corrupted"
.IP response_no_group 8
.IX Item "response_no_group"
.IP response_no_article 8
.IX Item "response_no_article"
.IP response_dup_article 8
.IX Item "response_dup_article"
.IP response_old_article 8
.IX Item "response_old_article"
.RE
.RS 4
.PD
.Sp
Fatal error responses:
.IP response_fatal 8
.IX Item "response_fatal"
.PD 0
.IP response_bad_request 8
.IX Item "response_bad_request"
.IP response_oversized 8
.IX Item "response_oversized"
.IP response_wrong_state 8
.IX Item "response_wrong_state"
.IP response_wrong_version 8
.IX Item "response_wrong_version"
.IP response_failed_auth 8
.IX Item "response_failed_auth"
.RE
.RS 4
.PD
.Sp

.RE
.IP "tag :all" 4
.IX Item "tag :all"
All of the above.
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
.Vb 4
\&    $client = INN::ovsqlite_client::\->new(
\&        path => $path,
\&        mode => $mode,         # optional, default 0 (read only)
\&    );
.Ve
.PP
Croaks on failure.
.SH METHODS
.IX Header "METHODS"
All request methods return the response code and store any error message in
the optional \f(CW\*(C`errmsg\*(C'\fR named argument.
.PP
Communication or protocol errors (as opposed to server errors) cause croaks.
.IP set_cutofflow 4
.IX Item "set_cutofflow"
.Vb 4
\&    $code = $client\->set_cutofflow(
\&        cutofflow  => $cutofflow,     # optional, default 0 (false)
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.IP add_group 4
.IX Item "add_group"
.Vb 7
\&    $code = $client\->add_group(
\&        groupname  => $groupname,
\&        low        => $low,
\&        high       => $high,
\&        flag_alias => $flag_alias,
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.IP get_groupinfo 4
.IX Item "get_groupinfo"
.Vb 8
\&    $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
\&    );
.Ve
.IP delete_group 4
.IX Item "delete_group"
.Vb 4
\&    $code = $client\->delete_group(
\&        groupname  => $groupname,
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.IP list_groups 4
.IX Item "list_groups"
.Vb 6
\&    $code = $client\->list_groups(
\&        groupid    => $groupid,       # optional in/output, default 0
\&        readsize   => $readsize,      # optional, default 0x20000
\&        groups     => $groups,        # output
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.Sp
\&\f(CW\*(C`$groups\*(C'\fR is set to a reference to an array of references to hashes with
these keys:
.RS 4
.IP groupname 8
.IX Item "groupname"
.PD 0
.IP low 8
.IX Item "low"
.IP high 8
.IX Item "high"
.IP count 8
.IX Item "count"
.IP flag_alias 8
.IX Item "flag_alias"
.RE
.RS 4
.PD
.Sp

.RE
.IP list_groups_all 4
.IX Item "list_groups_all"
.Vb 5
\&    $code = $client\->list_groups_all(
\&        callback   => \e&callback,
\&        readsize   => $readsize,      # optional, default 0x20000
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.Sp
This convenience method calls \f(CW\*(C`list_groups\*(C'\fR repeatedly to fetch information
for all groups.  The callback function is called with the \fIgroups\fR array
reference as the only argument.  It should return a true value to keep
iterating or a false value to terminate.
.IP add_article 4
.IX Item "add_article"
.Vb 9
\&    $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
\&    );
.Ve
.IP get_artinfo 4
.IX Item "get_artinfo"
.Vb 6
\&    $code = $client\->get_artinfo(
\&        groupname  => $groupname,
\&        artnum     => $artnum,
\&        token      => $token,         # output
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.IP delete_article 4
.IX Item "delete_article"
.Vb 5
\&    $code = $client\->delete_article(
\&        groupname  => $groupname,
\&        artnum     => $artnum,
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.IP search_group 4
.IX Item "search_group"
.Vb 9
\&    $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
\&    );
.Ve
.Sp
\&\f(CW\*(C`$articles\*(C'\fR is set to a reference to an array of references to hashes with
these keys:
.RS 4
.IP artnum 8
.IX Item "artnum"
.PD 0
.IP arrived 8
.IX Item "arrived"
.IP expires 8
.IX Item "expires"
.IP token 8
.IX Item "token"
.IP overview 8
.IX Item "overview"
.RE
.RS 4
.PD
.Sp

.RE
.IP search_group_all 4
.IX Item "search_group_all"
.Vb 9
\&    $code = $client\->search_group_all(
\&        groupname  => $groupname,
\&        low        => $low,
\&        high       => $high,          # optional
\&        cols       => $cols,          # optional, default 0x00
\&        callback   => \e&callback,
\&        readsize   => $readsize,      # optional, default 0x20000
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.Sp
This convenience methods calls \f(CW\*(C`search_group\*(C'\fR repeatedly to fetch information
for all specified articles.  The callback function is called with the
\&\fIarticles\fR array reference as the only argument.  It should return a true
value to keep iterating or a false value to terminate.
.IP start_expire_group 4
.IX Item "start_expire_group"
.Vb 4
\&    $code = $client\->start_expire_group(
\&        groupname  => $groupname,
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.IP expire_group 4
.IX Item "expire_group"
.Vb 5
\&    $code = $client\->expire_group(
\&        groupname  => $groupname,
\&        artnums    => \e@artnums,
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.Sp
\&\f(CW\*(C`@artnums\*(C'\fR must be an array of article numbers.
.IP finish_expire 4
.IX Item "finish_expire"
.Vb 3
\&    $code = $client\->finish_expire(
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.IP finish_expire_all 4
.IX Item "finish_expire_all"
.Vb 4
\&    $code = $client\->finish_expire_all(
\&        callback   => \e&callback,
\&        errmsg     => $errmsg,        # optional output
\&    );
.Ve
.Sp
This convenience method calls \f(CW\*(C`finish_expire\*(C'\fR 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.
.SH HISTORY
.IX Header "HISTORY"
Initial implementation and documentation written by Bo Lindbergh for
InterNetNews.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perl(1), ovsqlite\-server(8).