Added README file for addressbook migration test

This file details the addressbook migration test
which has a few components, and lists some details
on how to maintain the test.
Include locale.h where needed
EBookBackendSqliteDB: Fix introspect_summary()

Fixed introspect_summary() to resolve whether the summary
configuration has any attribute lists.
EBookBackendSqliteDB: introspect summary structure before adding columns.

Some additional auxilary columns need to be added in upgrades, these
columns which need to be added depend on which contact fields are
in the summary. This patch ensures that the summary is properly
introspected before adding columns, so that the right columns are added.
Tests: Added 3 new contacts and a few more query tests.

The new tests check some specific phone number matching cases
with E_BOOK_QUERY_EQUALS_NATIONAL_NUMBER queries.
test-server-utils: Add e_test_server_utils_run_full()

Basically this is to tell e_test_server_utils_run() to not
wipe the working directory before start.

Conflicts:

	tests/test-server-utils/e-test-server-utils.h
Added detection of ICU libs to configure.ac
Added utility ECollator to libedataserver.

The ECollator API wraps up the required ICU APIs into something more
convenient for usage in EDS. The provided features allow for rich
locale sensitive sorting as well as knowledge of the user's native
alphabet.

Some auxilary objects are needed to access features in ICU which are
available only in C++:

    EAlphabetIndex

    A private accessory used internally by ECollator to implement AlphabeticIndex
    features. This is in a separate file since we need to use C++ APIs to use
    the AlphabeticIndex, so we compile it into a separate archive to be statically
    linked in with libedataserver.la.

    ETransliterator

    Added this glue to call icu::Transliterator C++ APIs on behalf of ECollator.
Adding D-Bus API for cursor related APIs

  o org.freedesktop.locale1

    We generate a GDBus object to deal with the "org.freedesktop.locale1" interface
    on the system bus, specifically we are interested in system wide locale change
    notifications.

  o org.gnome.evolution.AddressBook

    Added the "Locale" property and added a method
    to create a cursor.

  o org.gnome.evolution.dataserver.AddressBookCursor

    The new D-Bus interface to interact with cursors.
EBookBackendSqliteDB: Adding cursor related APIs

Added the following APIs:

      o e_book_backend_sqlitedb_cursor_new()

        Creates a cursor for a given query expression and sort order

      o e_book_backend_sqlitedb_cursor_free()

        Frees a cursor and it's resources

      o e_book_backend_sqlitedb_cursor_move_by()

        Moves the cursor and fetches results

        Moving the cursor now has 3 possible "origins":

          o EBSDB_CURSOR_ORIGIN_CURRENT:
            Fetch results and move from the current
            cursor position

          o EBSDB_CURSOR_ORIGIN_PREVIOUS:
            Fetch results and move from the previous
            cursor position, practical for refreshing
            a result set after the addressbook changes

          o EBSDB_CURSOR_ORIGIN_RESET:
            Fetch results from the beginning (or end,
            if moving backwards through results).

        To achieve the EBSDB_CURSOR_ORIGIN_PREVIOUS origin, the cursor
        holds on to two cursor states at all times (the current cursor
        state and previous cursor state).

      o e_book_backend_sqlitedb_cursor_set_target_alphabetic_index()

        To set the cursor target by alphabetic index, also added
        e_book_backend_sqlitedb_ref_collator() to get a hold of the active
        collator which can be used to list the active alphabet attributes.

      o e_book_backend_sqlite_cursor_calculate()

        Calculates the position / total values of a cursor.

      o e_book_backend_sqlitedb_cursor_set_sexp()

        Sets the search expression for a given cursor

      o e_book_backend_sqlitedb_get/set_locale()

        Locale setting is now only ever guessed when creating a new addressbook
        before e_book_backend_sqlitedb_set_locale() is called, setting the locale
        will save the localization setting and it will be reused on subsequent
        accesses. If and when a locale setting is changed, the contact sort
        keys are regenerated with a new ECollator for the new locale.

      o e_book_backend_sqlitedb_cursor_compare()

        An api to compare the cursor with an EContact, this allows
        EDataBookCursor to track total / position when the addressbook is
        modified without constantly recalculating it with SQLite queries.
EBookBackend: Adding cursor related APIs

Added new ->set_locale() API and ->get_locale() API

Use these to dynamically set the locale of a running addressbook, and also
to fetch the currently configured locale of an addressbook at startup time

Also added new methods for creating and deleting cursors.
Added EDataBookCursor & EDataBookCursorSqlite

EDataBookCursor is an abstract class with the mid-level cursor APIs, it
takes care of responding to D-Bus APIs and provides an API which can
be used in Direct Read Access mode but does not implement the actual
cursor state and navigation directly.

EDataBookCursorSqlite is a cursor implementation which uses
a EBookBackendSqliteDB cursor to implement the EDataBookCursor
methods.

This patch also adds the E_CLIENT_ERROR_END_OF_LIST error, intended
to be a generic boundary error when a client api reaches the end
of some list of data (this is used by the cursor API of course
to report an error when trying to navigate the cursor outside of the
list boundaries).
EDataBook: Cursor related changes

Watch the system bus for locale notifications

When org.freedesktop.locale1 is available, listen to changes in
the LC_COLLATE locale and configure backends with locale changes
using e_book_backend_set_locale(), notify property changes via
the locale property on the addressbook D-Bus API.

Also, load the backend's initially set locale as the locale property
value until the org.freedesktop.locale1 D-Bus interface notifies
us of a locale change on the system bus.

Also handle D-Bus calls for creating cursors and export new
cursors on the bus.
EBookBackendFile: Implement cursors.

  o Implemented EBookBackend.create_cursor() and EBookBackend.delete_cursor()
    methods using the EDataBookCursorSqlite implementation

  o Ensure that all addressbook modifications and revision changes are
    atomic operations, the revision changes happen in the same transactions
    as any other addressbook modification (allowing revision checks to be
    done safely in direct read access mode).

  o Implement EBookBackend->set_locale() & ->get_locale()
Added EBookClientCursor

The user facing cursor API, deals with calling cursor APIs in DRA mode
and normal modes over D-Bus, handles threading situations, and notifies
of cursor state changes in the caller's main context.
EBookClient: Implemented e_book_client_get_cursor() and locale property

Propagate the 'locale' property change notifications when the dbus
proxy notifies a locale property change, also load the initial value
of the dbus proxy's locale property for the initial value.
Added tests for the low level cursor API

  o test-sqlite-create-cursor

    The new test case verifies that cursor creation is well protected
    (cursor creation is denied for some queries and ordering requests).

  o test-sqlite-cursor-move-by

    This test case asserts that e_book_backend_sqlite_cursor_move_by()
    works as expected. Consequently, a hand full of additional test
    vcards were added for this.

  o test-sqlite-cursor-set-target.c

    This test case tests e_book_backend_sqlitedb_cursor_set_target().

    The special case of setting a partial state is tested so that when
    a cursor is setup to sort by "family_name, given_name" and the target
    is set to "J", then we recieve results inclusive of the contact with
    the family name "J".

  o test-sqlite-cursor-calculate.c

    This test verifies that e_book_backend_sqlitedb_cursor_calculate() report
    the right position and total values when the cursor is moved, after the
    target is set, after the addressbook is modified, for filtered and unfiltered
    result sets.

  o test-sqlite-cursor-set-sexp.c

    This test verifies that invalid queries are rejected, and that a cursor
    position is changed by the new sexp with the correct new filtered values
    after applying a filter (sexp) to the cursor.

  o Tests to ensure that localized data is properly migrated:
      - test-sqlite-cursor-posix-initial
      - test-sqlite-cursor-en-US-migrated
      - test-sqlite-cursor-fr-CA-migrated
      - test-sqlite-cursor-de-DE-migrated
      - test-sqlite-cursor-posix-migrated

  o A test case testing basic ECollator features.

This patch also changes the test case vcard data to
specify a contact UID in each vcard's .vcf file, this
allows us more flexability with the above added tests.
Added tests for EBookClientCursor

 o test-client-cursor-create.c

    This test checks expected failure error codes and expected successfull
    cursor creation in Sync / Async and Normal / DRA modes.

 o test-client-cursor-operations.c

   A more complex set of tests which run in all various modes
   and configurations (i.e. Sync / Async / DRA / Threaded)
Adding cursor example program

The example program is a contact browser showing off
some of the cursor features such as localized alphabetic indexes.
Added new cursor related APIs to the documentation build.