The word "source" implies reading, while in fact access is read/write.
"datastore" avoids that misconception. Writing it in one word emphasizes
that it is single entity.
While renaming, also remove references to explicit --*-property
parameters. The only necessary use today is "--sync-property ?"
and "--datastore-property ?".
--datastore-property was used instead of the short --store-property
because "store" might be mistaken for the verb. It doesn't matter
that it is longer because it doesn't get typed often.
--source-property must remain valid for backward compatility.
As many user-visible instances of "source" as possible got replaced in
text strings by the newer term "datastore". Debug messages were left
unchanged unless some regex happened to match it.
The source code will continue to use the old variable and class names
based on "source".
Various documentation enhancements:
Better explain what local sync is and how it involves two sync
configs. "originating config" gets introduces instead of just
"sync config".
Better explain the relationship between contexts, sync configs,
and source configs ("a sync config can use the datastore configs in
the same context").
An entire section on config properties in the terminology
section. "item" added (Todd Wilson correctly pointed out that it was
missing).
Less focus on conflict resolution, as suggested by Graham Cobb.
Fix examples that became invalid when fixing the password
storage/lookup mechanism for GNOME keyring in 1.4.
The "command line conventions", "Synchronization beyond SyncML" and
"CalDAV and CardDAV" sections were updated. It's possible that the
other sections also contain slightly incorrect usage of the
terminology or are simply out-dated.
The notification texts were already localized, but using localization was not
turned on in the D-Bus server. The code which was meant to turn it on was
incomplete.
The setlocale() is required and was only done indirectly in syncevolution.org
binaries if the KDE platform module was installed. Now it is done in main() as
part of the process setup. Removed the incomplete setup code from the notify
backend completely (instead of fixing it) because a plugin should not modify
the process state like that.
As part of adding a test for this feature, a new environment was added: the
SYNCEVOLUTION_LOCALE_DIR environment variable can be set to the locale
directory which contains the different translations.
The English default text was already tested. The German translation gets
activated via env variables in the same test and checks that localization
works.
Now that translation is working, better ensure that English is selected
in those tests which expect English notifications.
Creating a database is only possible with a chosen name. The UID is
chosen automatically by the storage. A new property would be needed
to also specify the UID.
There are no command line tests for the new functionality because
support for it in backends is limited.
KWallet support was broken: syncevo-dbus-server checked
KDE_FULL_SESSION to determine whether it should use KWallet instead of
GNOME Keyring. That did not work, because the env variable was not set
for D-Bus daemons.
Automatically detecting KDE users is not possible at the
moment. Instead KDE users have to manually set the new "keyring"
global config property to "KDE" (case insensitive) if the
SyncEvolution installation supports both, because GNOME Keyring is the
default to avoid surprises for traditional users. If only KWallet
support is enabled, then this is not necessary.
"GNOME" and "true/false/1/0/yes/no" can also be set. This has the
advantage that keyring usage can be enabled permanently for the
command line in --daemon=no mode; normally keyrings are not used in
that mode because accessing them can bring up UI dialogs.
It also becomes possible to disable keyring usage in syncevo-dbus-server,
something which couldn't be done before.
The --keyring command line option is still supported, as an alias for
"[--sync-property] keyring=<value>". The default value for --keyring
is true, to match the traditional behavior. In contrast to other sync
properties, setting "keyring" does not require an explicit --run
parameter. Again this is done to mirror traditional usage.
Reading a password also (unintentionally) checked all supported
storages while searching for the password. Now it uses exactly
one storage and falls back to asking for the password directly.
The commit itself also cleans up the code a bit (reformatted, fixed
comments). Choosing the right slot in the password signals is done via
a new InitStateTri parameter which contains the "keyring" setting.
Error checking (unsupported keyring string, --keyring=yes and no
keyring enabled) is done in additional slots which run after all the
regular ones.
Parameter parsing for --sync and --keyring were unified. However,
there is the difference that --keyring has an implicit default value
("yes") and never has an additional parameter, in contrast to --sync,
which always is followed by one.
The new CmdlineTest::testKeyring covers different ways of using
--keyring. It relies on actually invoking keyring backends, something
not done by the default SyncContext UI. Therefore
CmdlineSyncClient+KeyringSyncCmdline were moved into libsyncevolution,
to be used by CmdlineTest.
Added code which checks for existence of the helper binary in the
libexec dir when it is given without any path component. Searching
inside the PATH env variable is still used as fallback when not
found in libexec (useful for testing without actually installing
in the final destination).
Conflicts:
Makefile.am
configure-post.in
configure.ac
src/Makefile-gen.am
src/dbus/qt/Makefile.am
src/syncevo-dbus-server.cpp
test/test-dbus.py
Conflicts caused by renaming of files on master. Manually applied the
relevant changes to the renamed files.
The <<insert sync/source-property>> tags were visible in the --help
output. Now it says
<< see "syncevolution --sync/source-property ?" >>
These special tags still get expanded in README and man page.
That expansion is done by invoking the uninstalled syncevolution
binary. If that failed, compilation aborted. That's still the case
for native compilation (because we want to catch problems). For
cross-compilation such a failure is okay and keeps the tags in
the README/man page. That's done because running a binary compiled
for an entirely different architecture is not guaranteed to work.
The need to add "foo" and "bar" pseudo config and source names to the
command line even when all parameters for the operation where
explicitly specified on the command line was confusing.
Now it is possible to invoke item operations without the config and
source name. Names which refer to non-existent configs are still
accepted, as in previous releases. Typos are handled better by
producing a detailed error report which includes (as applicable):
- config doesn't exist
- source doesn't exist or not selected
- backend property not set
This error report is created only if SyncSource was unable to create a
SyncSource, which is detected by catching the status exception with
the right error code. Trying to anticipate the error at the Cmdline
level would duplicate code found in the SyncSource and/or impose
limitations which might not hold in all cases.
Because luids used to be positional arguments after <config> and
<source>, a new --luids keyword is necessary to indicate that the
following parameters are luids and not <config> and <source>.
Added a CmdlineTest::testItemOperations for this new command line
syntax. It uses the file backend to run some real operations (missing
earlier).
Error reporting in the command line uses the same mix of writing error
messages and returning early (Cmdline) and throwing exceptions (rest
of SyncEvolution). Perhaps the Cmdline class should also use
exceptions - but not now.
The -from-client/server sync modes are confusing because the direction
of the data exchange depends on which side acts as SyncML server or
client.
This patch introduces new modes which use -from-local/remote
instead. The statistics and messages also use these variants now. The
old modes are still understood, but are declared as "not recommended"
in the documentation.
The README.rst now introduces some terms in a glossary directly after
the synopsis. The way how config, sources and properties are used on
the command line are also defined first in their own section, instead
of introducing that further down as part of the options.
The output of "--sync/source-property ?" was changed:
- now it includes information about aliases, default values
and sharing state (useful by itself)
- follows reStructured Text format and thus can be embedded
directly inside the README.rst
The Makefile rules for that will be committed in the next patch
(must be done differently on syncevolution-1-2 and master branch,
whereas this commit applies cleanly to both).
Listing databases is now a dedicated operation, instead of being done
whenever syncevolution was invoked without parameters.
Advantages:
- can be combined with property assignments for backends
which do not work without that additional information
- can be done for configured sources
Conflicts:
configure.ac
test/ClientTest.cpp
test/testcases/eds_event.ics.funambol.tem.patch
Conflicts because of version number and updated test cases resp. local
delete optimization.
ActiveSync backend had to be adapted to modified InsertItemResult: now
it requests a merge when it detects duplicates, like the CalDAV backend
already did on the 1.2 branch.
The warning about reversed data direction in local sync also applies
to syncing with a phone. Therefore the warning is now listed more
prominently below the "--sync" command line option and was extended to
also cover direct syncing.
In the past we have relied on the user-modifiable device name to be
the fingerprint for matching a phone to a template which is unreliable.
This commit changes this in the cases where the phone supports the
Device ID profile (DIP). If support DIP is detected then we extract
the vendor and product id's from the PnPInformation service
record. Then, we attempt to associate the ids with a product and
vendor name by using a newly added lookup table.
The preference for which value to use as the fingerprint is as
follows:
1) If the product is found in the lookup table we use
that. (The product lookup table is manually updated and currently
only has a few entries.)
2) Otherwise, we use the vendor name. (All vendors should be in the
lookup table, so this should always be used if the DIP is supported.
3) If the DIP is not supported by this device we fall back to using
the user-modifiable device name as before.
Additionaly, because the user-modifiable device name is still
desirable to expose through the dbus interface, it is now made
avaiable through the peerName property. This is intended to be used in
GUIs, for example.
Explicitly specifysing --sync/source-properties is no longer necessary.
The information about local sync and CalDAV/CardDAV must provide enough
information for normal users to use the feature.
SyncEvolution used to insist on having a template when creating a
config from scratch. This was meant to address typos like "--configure
sheduleworld". But when the command line contains enough information,
no template is needed.
The same logic was applied to configuring a source: if a source was not
among those defined by the template, configuring it was rejected as a
typo.
With this patch, there are two ways around these checks:
- --template none and/or
- specifying required properties on the command line
This patch also removes the special cases for "your SyncML server
account name/password". Username/password aren't always needed
(previous patch), nor are they always for a SyncML server anymore.
A double dash -- before the config name can be used to make it clear
where a options end and the config and source names start. Might be
useful when the config name contains an equal sign, because then it
would be treated like a property assignment.
The new format of the property name in --sync-property is:
<name>[@<context>|@<peer>@<context>]
--source-property also allows a source name:
[<source>/]<name>[@<context>|@<peer>@<context>]
This allows to set source properties differently for different
sources in the same command line invocation. The @<context> or
@<peer>@<context> will be used to set properties differently for
main and target context in a local sync (not used yet).
The advantage of this grammar is that a string can be split purely based
on the syntax in PropertySpecifier::StringToPropSpec().
The patch itself is based on the idea of first collecting all of these
config property filters in a new case-insensitive hash structure,
FullProps in ConfigFilter.cpp/h, as part of parsing command line
parameters.
Then once specific filters for sync or sources are needed, they are
generated from FullProps by collecting all that apply, starting with
the ones with lowest priority and overwriting them with more important
(= more specific) ones. This also covers additional filters, like the
shared properties of the target context when printing a template.
Currently FullProps may contain arbitrary source and config
names. Typos are not detected, which is both hard to implement (which
names and configs are valid in the current invocation?) and also
forces users to be very specific (can't apply one set of filters to
different configs) - this is the same conflict of interest as in
"configure", which allows unknown --enable/disable parameters because
they might be relevant in a sub-configure script.
SyncConfig itself still only stores the filters which apply to it, not
the full set of overrides that the Cmdline has in its m_props. The
advantage is that the API remains the same (no change needed or done
in the syncevo-dbus-server). The disadvantage is that in a local
sync, no information is available about the properties applying to the
target context - probably needs to change.
The ScheduleWorld service shut down end of November 2010.
Removing it completely from SyncEvolution is a bit
intrusive (it is used as reference configuration and in
unit tests), so this patch only makes it invisible to
sync-ui users and replaces it in the examples with
Memotoo.
There was no obvious way of deleting all items. Added * as wildcard
for that. It can be specified in addition to other luids, which
will be ignored if a star is given.
The --import operation was specified as splitting at a blank line and
was meant to work for vCard 3.0 and iCalendar 2.0 files. However, if
the blank line between items used DOS line ends (\r\n) like the items
themselves, then splitting them didn't work because of the literal
match with "\n\n".
This patch introduces a special semantic for the "\n\n" delimiter:
it also matches "\n\r\n" when splitting. This is implemented by
the custom FindDelimiter class.
Matthijs Kooijman recently started using SyncEvolution and took notes
about unclear explanations and missing information (--daemon!). This
useful feedback allowed to improve the documentation.
This patch adds an utility script (readme2c.pl) which extracts the
SYNOPSIS and OPTIONS part of README.rst and puts it into C
strings. These are then used inside the SyncEvolution command line for
short help (just the synopsis) and --help (also all options).
This patch also cleans up README.rst so that the OPTIONS part really
documents most options in sufficient detail for --help to be useful.
The USAGE section remains part of the README and the man page where
the different operations are introduced in a more task-oriented way.
This separation is not always easy to make. The --restore operation
and related parameters are only described in the USAGE part because I
couldn't find a way to introduce them briefly and then add a thorough
explanation under OPTIONS.
This complements --import/update/export/list-items. --remove was
already taken, for deleting a configuration.
Because the removal is done via the normal m_deleteItem operation, we
inherit the normal SyncML behavior (logging, no error return code for
non-existent items). It would have been nice to let the user choose
how to handle that situation (like --force in rm), but that can't be
done without SyncSource API changes.
These operations provide a common interface for manipulating
databases supported by SyncEvolution backends. --delete is
an obvious gap, will be added soon.
The implementation supports all backends offering the SyncSourceRaw
interface (Evolution, Akonadi, XMLRPC, file, but not the sqlite demo),
which is determined via a dynamic cast. SyncSourceRaw is necessary
because it allows direct access to the native data format without
going through the Synthesis engine.
Because the Synthesis engine is not activated, printing the short
description (SyncSourceLogging interface) mentioned in the README.rst
is not possible yet. Having such an engine would be useful also for
importing/exporting data which is not in the native format of the
backend; additional command line parameters will be needed to define
that format.
All of the new operations have in common that they work on one source
and multiple LUIDs. This is a slight deviation from other command line
synopsises where all arguments after the server config refer to sources.
The new m_accessItems flag is set for these special operations; they
also share much of the setup code.
The implementation itself tries to use the generic SyncSource
interface as much as possible. It only falls back to more specialized
implementations where necessary (SyncSourceRaw).
The builtin synopsis and usage was intentionally not updated. The
expection is that before this patch lands in the "master" branch, the
builtin text will come directly from README.rst (which was updated).
Reorganized the content so that it is more like a man reference page.
Known problems, setup, feature overview are meant to be maintained
at syncevolution.org.
Changed the format to reStructuredText (http://docutils.sourceforge.net/rst.html).
It can already be converted to man format (rst2man) and HTML for the
Drupal installation on syncevolution.org. Line breaks are problematic
when copying the HTML source because Drupal turns line breaks into <br/>.
The goal is that the README.rst is the authoritative copy of the
syncevolution.org "Usage" page and a "syncevolution/synccompare" man
page.
Patrick Ohly
Chris Kühl