vCard 3.0 validator and parser

Did you know that even the vCards listed in the official RFC are not valid? It clearly says The vCard object MUST contain the FN, N and VERSION types. Still, the example vCards are both clearly missing the N type. As somebody else remarked, releasing a format spec without some reference validator is bound to result in all sorts of invalid implementations.

After searching for a vCard validator without success, I’ve therefore started my own vCard module in Python. It tries to create an object with all the information from a vCard string, and returns what I hope are useful error and warning messages if there’s anything wrong.

Update: Added file validation – Now you can validate files with several vCards from the command line.

Install / upgrade:
sudo pip install --upgrade vcard

Validate vCard files:
vcard *.vcf

HOWTO: Synchronizing vCard address books with Nokia 6300 via Bluetooth on Ubuntu Linux

Edit: After learning a bit of sed magic, this is now a single script.

This Works For Me™, and I hope it works with other phones and on other distributions as well, but no guarantees.

Here’s how:

  1. Download synchronize-bluetooth.sh.
  2. chmod u+x synchronize-bluetooth.sh
  3. sudo apt-get install gnokii
  4. Setup Gnokii (replace the phone name): echo -e "[global]\nmodel = 6510\nport = $(hcitool scan | grep 'phone name' | cut --fields=2)\nconnection = bluetooth" > ~/.gnokiirc
  5. Turn Bluetooth on on the computer and the phone.
  6. Pair the computer and phone. On Ubuntu, simply click the Bluetooth icon and follow the "Set up new device..." wizard.
  • If you want to copy your existing contacts to disk, you can run ./synchronize-bluetooth.sh -r > phone.vcf
  • To copy vCards to the phone, overwriting the existing contacts, run cat *.vcf | ./synchronize-bluetooth.sh -f
  • Note that synchronize-bluetooth.sh works only with the internal phone memory. Address book entries stored in the SIM card, phone log or elsewhere will not be read or written.

    Some features of the script:

    • Works with plain /bin/sh, so it should work on any Linux / BSD distribution.
    • Has separate parameters to read, write and flush contacts.

    synchronize-bluetooth.sh

    #!/bin/sh
    #
    # NAME
    #    synchronize-bluetooth.sh - Synchronize contacts with Bluetooth device.
    #
    # SYNOPSIS
    #    synchronize-bluetooth.sh [options]
    #
    # OPTIONS
    #    -f,--flush       Flush entries on the phone before synchronization
    #    -r,--read        Read phonebook entries (no synchronization)
    #
    # EXAMPLES
    #    ./synchronize-bluetooth.sh -r
    #        Read phone address book entries.
    #
    #    cat *.vcf | ./synchronize-bluetooth.sh -fv
    #        Remove all phone address book entries and write new ones.
    #
    # DESCRIPTION
    #    Warning: Overwrites the existing entries on the phone if you give it any
    #    input.
    #
    #    Some limitations:
    #    - Gnokii (or the phone) doesn't understand N, NICKNAME, ORG and URL
    #      parameters.
    #    - Conflicts have to be resolved manually.
    #    - Getting a "Data format is not valid" error for unknown reasons.
    #    - Needs conv.pl so long as Gnokii / phone doesn't understand the full vCard
    #      spec.
    #
    #    Tested on Nokia 6300 under Ubuntu (7.10-9.10). Instructions:
    #    <https://l0b0.wordpress.com/2008/03/18/howto-copying-vcard-address-books-to-nokia-6300-via-bluetooth-on-ubuntu-linux/>
    #
    # BUGS
    #    1: Not yet tested on other phones or operating systems.
    #    2: No automated comparison of computer and phone entries.
    #    3: Should use safe temporary directory creation - See web pages.
    #    4: Flushing doesn't always get rid of all address book entries.
    #
    #    Email bugs to victor dot engmark at gmail dot com. Please include the
    #    output of running this script.
    #
    # COPYRIGHT AND LICENSE
    #    Copyright (C) 2008-2010 Victor Engmark
    #
    #    This program is free software: you can redistribute it and/or modify
    #    it under the terms of the GNU General Public License as published by
    #    the Free Software Foundation, either version 3 of the License, or
    #    (at your option) any later version.
    #
    #    This program is distributed in the hope that it will be useful,
    #    but WITHOUT ANY WARRANTY; without even the implied warranty of
    #    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    #    GNU General Public License for more details.
    #
    #    You should have received a copy of the GNU General Public License
    #    along with this program.  If not, see <http://www.gnu.org/licenses/>.
    #
    ################################################################################
    
    # Init
    PATH='/usr/bin:/bin'
    ifs_original="$IFS" # Reset when done
    cmdname=$(basename $0)
    directory=$(dirname $0)
    
    # Exit codes from /usr/include/sysexits.h, as recommended by
    # http://www.faqs.org/docs/abs/HTML/exitcodes.html
    EX_USAGE=64
    
    # Output error message with optional error code
    error()
    {
        test -t 1 && {
            tput setf 4
            echo "$1" >&2
            tput setf 7
        } || echo "$1" >&2
        if [ -z "$2" ]
        then
            exit $EX_UNKNOWN
        else
            exit $2
        fi
    }
    
    usage()
    {
        # Print documentation until the first empty line
        while read line
        do
            if [ ! "$line" ]
            then
                exit $EX_USAGE
            fi
            echo "$line"
        done < $0
    }
    
    # Process parameters
    params=$(getopt -o fr -l flush,read --name $cmdname -- "$@")
    if [ $? -ne 0 ]
    then
        usage
    fi
    
    eval set -- "$params"
    
    while true
    do
        case $1 in
            -f|--flush)
                flush=1
                shift
                ;;
            -r|--read)
                read=1
                shift
                ;;
            --) shift
                break
                ;;
            *)
                usage
                ;;
        esac
    done
    
    if [ $read ]
    then
        gnokii --getphonebook ME 1 end --vcard \
            || error 'Failed to get phonebook.'
        exit
    fi
    
    if [ $flush ]
    then
        gnokii --deletephonebook ME 1 end \
            || error 'Could not flush phone entries.'
    fi
    
    sleep 1
    
    # Is there anything on stdin?
    if [ -t 0 ]
    then
        exit
    fi
    
    sed -n '1h;1!H;${;g;s/\r\n //g;p}' <&0 | \
    sed -E s/^ADR\;.*?\(home\|work\).*?:/ADR\;TYPE=\\1:/i\;s/^EMAIL\;.*?\(INTERNET\).*?:/EMAIL\;TYPE=\\1:/i\;s/^TEL\;.*?\(CELL\|FAX\|HOME\|WORK\).*?:/TEL\;TYPE=\\1:/i | \
    gnokii --writephonebook --overwrite --memory-type ME --vcard
    
    err_code=$?
    if [ $err_code -eq 20 ]
    then
        echo 'Data format error, eh? Dunno what to do about that for now.'
    elif [ $err_code -ne 0 ]
    then
        error 'Could not write to phone.' $err_code
    fi

    If you have problems sending the vCards to your phone, you may want to validate them first.

    How to serve vCards with the right encoding

    It seems that some programs which recognize vCards only support the ISO-8859-1 character set. So if you’re serving vCards on your web site, you might want to check if the encoding is correct. Try inserting a non-ASCII character like “å” in a note or address, and see if it comes out as a strange character when loading it from the web site.

    To fix this, first make sure that your editor uses the correct encoding. Open the file, change the encoding, save the file, re-open it and correct the contents if the characters were messed up after saving (not all editors change characters correctly).

    You might also have to override the server’s default encoding. If you’re using Apache 2, just add the following to the .htaccess file at the root of the web site:
    AddCharset ISO-8859-1 .vcf
    AddEncoding text/x-vcard .vcf

    Turns out that didn’t work so well (I didn’t find out until i did a shift-reload). I had to turn to this one instead:
    <Files *.vcf>
    ForceType 'text/x-vcard; charset=ISO-8859-1'
    </Files>