<?xml version="1.0" ?>
<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<refentry lang="&language;">
<refentryinfo>
<title>&kde; User's Manual</title>
<author>
  <firstname>Kevin</firstname>
  <surname>Krammer</surname>
  <affiliation>
    <address><email>kevin.krammer@gmx.at</email></address>
  </affiliation>
  <contrib>Author</contrib>
</author>
<date>2005-09-08</date>
<productname>K Desktop Environment</productname>
</refentryinfo>

<refmeta>
<refentrytitle><command>kabcclient</command></refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv id='name'>
<refname>kabcclient</refname>
<refpurpose>commandline client for the &kde; addressbook</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv id='synopsis'>
<cmdsynopsis>
  <command>kabcclient</command> 
    <group>
    <arg choice="opt">-A</arg>
    <arg choice="opt">-R</arg>
    <arg choice="opt">-M</arg>
    <arg choice="opt">-S</arg>
    <arg choice="opt">-L</arg>
    </group>
    <arg choice="opt">--match-case</arg>
    <arg choice="opt">--nosave</arg>
    <arg choice="opt">-ic <replaceable>codec</replaceable></arg>
    <arg choice="opt">-if <replaceable>format</replaceable></arg>
    <arg choice="opt">-if-opts <replaceable>format-options</replaceable></arg>
    <arg choice="opt">-oc <replaceable>codec</replaceable></arg>
    <arg choice="opt">-of <replaceable>format</replaceable></arg>
    <arg choice="opt">-of-opts <replaceable>format-options</replaceable></arg>
    <arg choice="opt"> input-data </arg>

</cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'>
<title>Description</title> 
<para><command>kabcclient</command>
allows commandline access to the &kde; addressbook, for example in shell scripts.
It supports input from stdin or through additional commandline arguments.
Output is always written to stdout.</para>
</refsect1>

<refsect1 id='options'>
<title>Options</title>
<variablelist>

<varlistentry>
<term><emphasis>Operation modes</emphasis></term>
<listitem>
<variablelist>

<varlistentry>
  <term><option>-A, --add</option></term>
  <listitem>
<para>Add a new contact entry to the addressbook</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-R, --remove</option></term>
  <listitem>
<para>Removes an existing contact entry from the addressbook</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-M, --merge</option></term>
  <listitem>
<para>Merges input data with an existing contact entry from the addressbook.
This appends any new information to the already existing one</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-S, --search</option></term>
  <listitem>
<para>Searches the addressbook for matching contact entries</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-L, --list</option></term>
  <listitem>
<para>Lists all contact entries of the addressbook</para>
  </listitem>
  </varlistentry>

</variablelist>
</listitem>
</varlistentry>


<varlistentry>
<term><emphasis>Input options</emphasis></term>
<listitem>
<variablelist>

  <varlistentry>
  <term><option>-ic, --input-codec</option></term>
  <listitem>
<para>Pass input text through a specified text encoding. See
<option>-ic</option><replaceable> help</replaceable>
for additional information about input codecs. Default is
<emphasis>local</emphasis>
which will use the codec for the current
<citerefentry><refentrytitle>locale</refentrytitle><manvolnum>5</manvolnum></citerefentry>
settings</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-if, --input-format</option></term>
  <listitem>
<para>Parses the input text according to given formatting rules. See
<option>-if</option><replaceable> help</replaceable>
for available formats. Default is
<emphasis>search</emphasis></para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term>Instead of reading input text kabcclient can show a dialog for selecting contacts using the input format</term>
  <listitem>
<para><emphasis>dialog</emphasis></para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-if-opts, --input-format-options</option></term>
  <listitem>
<para>Additional options for the chosen input format. Can be optional as well as
mandatory depending on the format. See
<option>-if-opts</option><replaceable> help</replaceable>
for available format options</para>
  </listitem>
  </varlistentry>

</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis>Output options</emphasis></term>
<listitem>
<variablelist>

  <varlistentry>
  <term><option>-oc, --output-codec</option></term>
  <listitem>
<para>Pass output text through a specified text encoding. See
<option>-oc</option><replaceable> help</replaceable>
for additional information about output codecs. Default is
<emphasis>local</emphasis>
which will use the codec for the current
<citerefentry><refentrytitle>locale</refentrytitle><manvolnum>5</manvolnum></citerefentry>
settings.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-of, --output-format</option></term>
  <listitem>
<para>Formats the output text according to given formatting rules. See
<option>-of</option><replaceable> help</replaceable>
for available formats. Default is
<emphasis>vcard</emphasis>.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>-of-opts, --output-format-options</option></term>
  <listitem>
<para>Additional options for the chosen output format. Can be optional as well as
mandatory depending on the format. See
<option>-of-opts</option><replaceable> help</replaceable>
for available format options</para>
  </listitem>
  </varlistentry>

</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis>Additional options</emphasis></term>
<listitem>
<variablelist>

  <varlistentry>
  <term><option>--match-case</option></term>
  <listitem>
<para>Use case sensitive text matching when comparing input text with contact entries</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><option>--nosave</option></term>
  <listitem>
<para>Perform information changing operations like
<option>-A, -R</option>
or
<option>-M</option>
only in memory but do not write the changes back to the addressbook</para>
  </listitem>
  </varlistentry>

</variablelist>
</listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1 id='diagnostics'>
<title>Diagnostics</title>
<para>As usual an exit status of zero indicates success.
Depending on the chosen operation mode a non-zero exit status indicates
a certain problem the application encountered</para>
<variablelist>

<varlistentry>
<term><emphasis>ADD</emphasis></term>
<listitem>
<variablelist>

  <varlistentry>
  <term><literal>1</literal></term>
  <listitem>
<para>Reading the input text failed</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><literal>2</literal></term>
  <listitem>
<para>Creating a suitable contact entry from the input text failed, e.g. not
data or wrongly formatted input for the chosen input format</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><literal>3</literal></term>
  <listitem>
<para>Saving the addressbook changes failed. This can be caused for example by
other applications currently locking the addressbook.</para>
  </listitem>
  </varlistentry>

</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis>REMOVE</emphasis></term>
<listitem>
<variablelist>

  <varlistentry>
  <term><literal>1</literal></term>
  <listitem>
<para>Reading the input text failed</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><literal>2</literal></term>
  <listitem>
<para>The program could not remove any contact entry from the addressbook. This
can be caused by failing to parse the input text, failing to find a matching
contact entry in the addressbook or finding more than one matching contact
entry in the addressbook. In the latter case an error message is written to
stderr</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><literal>3</literal></term>
  <listitem>
<para>Saving the addressbook changes failed. This can be caused for example by
other applications currently locking the addressbook.</para>
  </listitem>
  </varlistentry>

</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><emphasis>MERGE</emphasis></term>
<listitem>
<variablelist>

  <varlistentry>
  <term><literal>1</literal></term>
  <listitem>
<para>Reading the input text failed</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><literal>2</literal></term>
  <listitem>
<para>The program could not merge the input with any contact entry from the addressbook.
This can be caused by failing to parse the input text, failing to find a matching
contact entry in the addressbook or finding more than one matching contact
entry in the addressbook. In the latter case an error message is written to
stderr</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><literal>3</literal></term>
  <listitem>
<para>Saving the addressbook changes failed. This can be caused for example by
other applications currently locking the addressbook.</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><emphasis>SEARCH</emphasis></term>
  <term><literal>1</literal></term>
  <listitem>
<para>Reading the input text failed</para>
  </listitem>
  </varlistentry>
  <varlistentry>
  <term><literal>2</literal></term>
  <listitem>
<para>The program could not find any matching contact entry in the addressbook.
This can be caused by failing to parse the input text or failing to find a matching
contact entry in the addressbook</para>
  </listitem>
  </varlistentry>

</variablelist>
</listitem>
</varlistentry>

</variablelist>
</refsect1>

<refsect1 id='examples'>
<title>Examples</title>
<para><emphasis>Look for contact entries with Joe in either name or email addresses</emphasis></para>
<literallayout>
kabcclient -S Joe
</literallayout>

<para><emphasis>Do the same but use case sensitive matching</emphasis></para>
<literallayout>
kabcclient --match-case -S Joe
</literallayout>

<para><emphasis>Do the same but read input text from stdin</emphasis></para>
<literallayout>
echo "Joe" | kabcclient --match-case -S
</literallayout>

<para><emphasis>Try to add a new contact entry using data from a formatted email address</emphasis></para>
<literallayout>
kabcclient --nosave --add -if email "Marilyn Monroe &lt;mmonroe@moviestars.com&gt;"
</literallayout> 

<para><emphasis>Do the same but this time really save the changed addressbook</emphasis></para>
<literallayout>
kabcclient --add -if email "Marilyn Monroe &lt;mmonroe@moviestars.com&gt;"
</literallayout>

<para><emphasis>Listing the available input formats</emphasis></para>
<literallayout>
kabcclient -if help
</literallayout>

<para><emphasis>Listing the available output formats</emphasis></para>
<literallayout>
kabcclient -of help
</literallayout>

<para><emphasis>Listing the available options for the 'email' output format</emphasis></para>
<literallayout>
kabcclient -of email -of-opts help
</literallayout>

<para><emphasis>Listing all email addresses for all contacts containing 'Marilyn'</emphasis></para>
<literallayout>
kabcclient -of email -of-opts allemails -S Marilyn
</literallayout>

<para><emphasis>Remove all contacts the user selected in the contact selection dialog</emphasis></para>
<literallayout>
kabcclient --remove -if dialog
</literallayout>

<para><emphasis>Export selected contacts to a vCard (default output format) file</emphasis></para>
<literallayout>
kabcclient -S -if dialog &gt; contacts.vcf
</literallayout>

</refsect1>

<refsect1 id='author'><title>Author</title>
<para>This manual page was written by Kevin Krammer &lt;kevin.krammer@gmx.at&gt;.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License, Version 2 any
later version published by the Free Software Foundation.</para>

<para>On Debian systems, the complete text of the GNU General Public License
can be found in /usr/share/common-licenses/GPL.</para>
</refsect1>
</refentry>